esi-sdk 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96bfde25cec60466f068690e618f8eb448f287686652529627d83e61bff6a27e
-  data.tar.gz: 30a10c563775c08ce91e003fa97a34b72dc48db1b754b39a34d7b7b7398fc3d0
+  metadata.gz: 32e80c8b57db70012c9002de31f5533508fc5144d6d416b5d5f3c1dd588805df
+  data.tar.gz: 1f20d6ef7531035b260c4b5d936ff4bed4f6ac1d9e3222a771c7717c4b8f236c
 SHA512:
-  metadata.gz: 4e3e48c1b7e9b03605e0a58a1b9cc7f7d47ae4180efbf0872aef6aec9b187c84febf354f86267694478802f001d2ab0dc5094091ba7789e3be00e16d2217a957
-  data.tar.gz: 7f241d000d376edd19b72e743e5f7f5176ce75c32df0468f1544fac413eaa659e651113c4b1332dfecd19f626f8412d9615cd326e85a4d92410cbe5f6ed1682a
+  metadata.gz: d2d30b0b42a5b16e4756f30fd5ed490e5129db9caa7e67ccac5bbc26ae17cb316589d38ce466daea8cb3b2eb4b2553a4385e8d780a1d786b56ce2cf61422d26b
+  data.tar.gz: 40b27c822b0356183a25b88aa6ddad08b975c152b772beae0ee2c047a4579483a9c8333879371db5e21c954bfffa75244e812df529331fe7d712bcf105943ecb

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ESI SDK Changelog
 
+# [1.2.0](https://github.com/bokoboshahni/esi-sdk-ruby/compare/v1.1.3...v1.2.0) (2021-07-20)
+
+
+### Features
+
+* Client improvements ([bad70ae](https://github.com/bokoboshahni/esi-sdk-ruby/commit/bad70ae4d97b8b0f93019b5b4dac73f97aad7dc0))
+
 ## [1.1.3](https://github.com/bokoboshahni/esi-sdk-ruby/compare/v1.1.2...v1.1.3) (2021-07-19)
 
 

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    esi-sdk (1.1.3)
+    esi-sdk (1.2.0)
       faraday (~> 1.5)
       faraday-http-cache (~> 2.2)
       faraday_middleware (~> 1.0)
+      typhoeus (~> 1.4)
 
 GEM
   remote: https://rubygems.org/
@@ -23,6 +24,8 @@ GEM
       rexml
     diff-lcs (1.4.4)
     docile (1.4.0)
+    ethon (0.14.0)
+      ffi (>= 1.15.0)
     faraday (1.5.1)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
@@ -44,6 +47,7 @@ GEM
     faraday-patron (1.0.0)
     faraday_middleware (1.0.0)
       faraday (~> 1.0)
+    ffi (1.15.3)
     hashdiff (1.0.1)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
@@ -102,6 +106,8 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.0.0)

data/README.md

@@ -1,3 +1,5 @@
+![Build images](https://github.com/bokoboshahni/esi-sdk-ruby/workflows/CICD/badge.svg)
+
 # EVE Swagger Interface (ESI) SDK
 
 ESI SDK is a Ruby API client for the EVE Swagger Interface (ESI), the official API for the [EVE Online](https://eveonline.com) MMORPG.
@@ -53,6 +55,19 @@ response = client.get_character(character_id: 2113024536)
 
 See the documentation for [ESI::Client](https://bokoboshahni.github.io/esi-sdk-ruby/ESI/Client.html) for detailed information on each endpoint.
 
+### Caching
+
+Caching is handled via the [faraday-http-cache](https://github.com/sourcelevel/faraday-http-cache) middleware. When instantiating an `ESI::Client` instance, cache configuration can be passed via the `cache` parameter:
+
+```ruby
+client = ESI::Client.new(
+  user_agent: 'My ESI Bot/1.0; +(https://example.com)',
+  cache: { store: Rails.cache, logger: Rails.logger, instrumenter: ActiveSupport::Notifications }
+)
+```
+
+See the [faraday-http-cache](https://github.com/sourcelevel/faraday-http-cache) documentation for more details on what configuration options are available.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -142,7 +142,7 @@ task :generate do
       end
 
       param_tags = operation[:params].map do |p|
-        "# @param #{p["name"]} [Integer,String] #{p["description"]}"
+        "# @param #{p["name"]} [#{p["type"].capitalize}] #{p["description"]}"
       end
 
       if operation[:body]
@@ -161,14 +161,26 @@ task :generate do
       end
 
       operation[:query]&.each do |p|
-        signature_params << "#{p["name"]}:"
-        param_tags << "# @param #{p["name"]} [#{p["type"].capitalize}] #{p["description"]}"
+        p_tag = "# @param #{p["name"]} [#{p["type"].capitalize}] "
+        p_tag += (p["description"]).to_s
+        p_tag += ". Must be one of: #{p["enum"].map { |e| "`#{e}`" }.join(", ")}" if p["enum"]
+        p_str = if p["default"] && p["type"] == "integer"
+                  "#{p["name"]}: #{p["default"]}"
+                elsif p["default"] && p["type"] == "string"
+                  "#{p["name"]}: \"#{p["default"]}\""
+                elsif !p["required"]
+                  "#{p["name"]}: nil"
+                else
+                  "#{p["name"]}:"
+                end
+        signature_params << p_str
+        param_tags << p_tag
       end
 
-      if %w[delete get].include?(operation[:method])
-        signature_params << "params: {}"
-        param_tags << "# @param params [Hash] Additional query string parameters"
+      signature_params += %w[headers params].map do |p|
+        "#{p}: {}"
       end
+      param_tags << "# @param params [Hash] Additional query string parameters"
 
       param_tags += [
         "# @param headers [Hash] Additional headers"
@@ -188,9 +200,6 @@ task :generate do
       description += "# @see https://esi.evetech.net/ui/#/#{operation[:tag]}/#{operation[:name]}"
       description.gsub!(/^$\n/m, "")
 
-      signature_params += %w[headers].map do |p|
-        "#{p}: {}"
-      end
       signature = "(#{signature_params.join(", ")})"
       path_parts = operation[:path].split("/")
       path_parts.map! do |p|
@@ -202,16 +211,12 @@ task :generate do
       end
       path = "#{path_parts.join("/")}/"
 
-      http_call_params = %w[headers].map { |p| "#{p}: #{p}" }
-      http_call_params << if %w[delete get].include?(operation[:method])
-                            "params: params"
-                          elsif operation[:body]
-                            "payload: #{body_param["name"]}"
-                          end
+      http_call_params = %w[headers params].map { |p| "#{p}: #{p}" }
+      http_call_params << ("payload: #{body_param["name"]}" if operation[:body])
 
       if operation[:query].any?
-        http_call = "query_string = URI.encode_www_form([#{operation[:query].map { |q| "['#{q["name"]}', #{q["name"]}]" }.join(", ")}])\n"
-        http_call += "#{operation[:method]}(\"#{path}?\#{query_string}\", #{http_call_params.join(", ")})"
+        http_call = "params.merge!(#{operation[:query].map { |q| "'#{q["name"]}' => #{q["name"]}" }.join(", ")})\n"
+        http_call += "#{operation[:method]}(\"#{path}\", #{http_call_params.join(", ")})"
       else
         http_call = "#{operation[:method]}(\"#{path}\", #{http_call_params.join(", ")})"
       end
@@ -269,11 +274,6 @@ task :generate do
       success_params = operation[:params].map { |p| "#{p["name"]}: \"1234567890\"" }
       success_params += operation[:query].map { |p| "#{p["name"]}: \"1234567890\"" }
 
-      if operation[:query].any?
-        query = URI.encode_www_form(operation[:query].map { |q| [q["name"], "1234567890"] })
-        success_path = "#{success_path}?#{query}"
-      end
-
       if operation[:body]
         body_param = operation[:body]
         body_name = body_param["name"]
@@ -287,12 +287,14 @@ task :generate do
         success_params << "#{body_name}: #{body_value}"
       end
 
+      with_query = operation[:query].any? ? ".with(query: { #{operation[:query].map { |p| "#{p["name"]}: \"1234567890\"" }.join(", ")} })" : ""
+
       describe = "  describe \"##{method_name}\" do\n"
       describe += "    context \"when the response is #{success_code}\" do\n"
       describe += "      let(:response) { #{success_response_body} }\n"
       describe += "\n"
       describe += "      before do\n"
-      describe += "        stub_request(:#{operation[:method]}, \"https://esi.evetech.net/latest#{success_path}\").to_return(body: response.to_json)\n"
+      describe += "        stub_request(:#{operation[:method]}, \"https://esi.evetech.net/latest#{success_path}\")#{with_query}.to_return(body: response.to_json)\n"
       describe += "      end\n"
       describe += "\n"
       describe += "      it \"returns the response\" do\n"
@@ -303,13 +305,15 @@ task :generate do
       describe += "\n"
 
       error_contexts = operation[:errors].map do |(code, error)|
+        next if %w[502 503 504].include?(code)
+
         error_response_body = error["examples"]["application/json"].inspect
 
         context = "    context \"when the response is #{code}\" do\n"
         context += "      let(:response) { #{error_response_body} }\n"
         context += "\n"
         context += "      before do\n"
-        context += "        stub_request(:#{operation[:method]}, \"https://esi.evetech.net/latest#{success_path}\").to_return(body: response.to_json, status: #{code})\n"
+        context += "        stub_request(:#{operation[:method]}, \"https://esi.evetech.net/latest#{success_path}\")#{with_query}.to_return(body: response.to_json, status: #{code})\n"
         context += "      end\n"
         context += "\n"
         context += "      it \"raises a #{error_mapping[code.to_i]} error\" do\n"
@@ -327,8 +331,8 @@ task :generate do
     spec_content = <<~SPEC_FILE
       # frozen_string_literal: true
 
-      RSpec.describe ESI::Client::#{module_name} do
-        subject(:client) { ESI::Client.new(user_agent: \"ESI SDK Tests/1.0; +(https://github.com/bokoboshahni/esi-sdk)\") }
+      RSpec.describe ESI::Client::#{module_name}, type: :stub do
+        subject(:client) { ESI::Client.new(user_agent: \"esi-sdk-ruby Tests/1.0; +(https://github.com/bokoboshahni/esi-sdk-ruby)\") }
 
       #{describe_blocks.join("\n\n")}
       end

data/esi-sdk.gemspec

@@ -29,4 +29,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "faraday", "~> 1.5"
   spec.add_dependency "faraday-http-cache", "~> 2.2"
   spec.add_dependency "faraday_middleware", "~> 1.0"
+  spec.add_dependency "typhoeus", "~> 1.4"
 end

data/lib/esi/client.rb

@@ -4,6 +4,8 @@ require "faraday"
 require "faraday-http-cache"
 require "faraday_middleware"
 require "timeout"
+require "typhoeus"
+require "typhoeus/adapters/faraday"
 
 require_relative "./errors"
 require_relative "./client/alliance"
@@ -95,18 +97,23 @@ module ESI
 
     # Returns a new {ESI::Client}.
     #
+    # See the [faraday-http-cache](https://github.com/sourcelevel/faraday-http-cache) documentation for information on
+    # how to set up caching via the `cache` parameter.
+    #
     # @param user_agent [String] Value of the `User-Agent` header for HTTP calls
     # @param base_url [String] The base URL of the ESI API
     # @param version [String] The version of the ESI API
     # @param cache [Hash] The cache configuration to use
+    # @param max_concurrency [Integer] Maximum concurrent requests for pagination
     # @option cache [Object] :store The cache store (e.g. `Rails.cache`)
     # @option cache [Object] :logger The logger (e.g. `Rails.logger`)
     # @option cache [Object] :instrumenter The instrumenter (e.g. `ActiveSupport::Notifications`)
-    def initialize(user_agent:, base_url: DEFAULT_BASE_URL, version: DEFAULT_VERSION, cache: {})
+    def initialize(user_agent:, base_url: DEFAULT_BASE_URL, version: DEFAULT_VERSION, cache: {}, max_concurrency: 50)
       @base_url = base_url
       @cache = cache
       @user_agent = user_agent
       @version = version
+      @hydra = Typhoeus::Hydra.new(max_concurrency: max_concurrency)
     end
 
     # Set the `Authorization` header for subsequent requests.
@@ -122,89 +129,104 @@ module ESI
     ESI_RETRY_EXCEPTIONS = [Errno::ETIMEDOUT, Timeout::Error, Faraday::TimeoutError, Faraday::ConnectionFailed,
                             Faraday::ParsingError, SocketError].freeze
 
+    attr_reader :hydra
+
     def delete(path, params: {}, headers: {})
       response = make_delete_request(path, params: params, headers: headers)
+      raise_error(response) unless response.success?
       response.body
     end
 
     def get(path, params: {}, headers: {})
       response = make_get_request(path, params: params, headers: headers)
+      raise_error(response) unless response.success?
 
-      return paginate(response, params, headers) if paginated?(response)
+      response_headers = normalize_headers(response.headers)
+      return paginate(response, path, params, headers) if paginated?(response_headers)
 
       response.body
     end
 
-    def post(path, payload: {}, headers: {})
-      response = make_post_request(path, payload: payload, headers: headers)
+    def post(path, payload: {}, params: {}, headers: {})
+      response = make_post_request(path, payload: payload, params: params, headers: headers)
+      raise_error(response) unless response.success?
       response.body
     end
 
-    def put(path, payload: {}, headers: {})
-      response = make_put_request(path, payload: payload, headers: headers)
+    def put(path, payload: {}, params: {}, headers: {})
+      response = make_put_request(path, payload: payload, params: params, headers: headers)
+      raise_error(response) unless response.success?
       response.body
     end
 
-    def paginate(response, params, headers)
+    def paginate(response, path, params, headers) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       all_items = response.body
-      page_count = response.headers["X-Pages"].to_i - 1
-      page_count.times do |n|
-        page_number = n + 1
-        params = params.merge(page: page_number)
-        page = make_get_request(path, params: params, headers: headers)
-        all_items += page.body
+      response_headers = normalize_headers(response.headers)
+      page_count = response_headers["x-pages"].to_i - 1
+
+      responses = []
+      url_encoded_connection.in_parallel(hydra) do
+        page_count.times do |n|
+          page_number = n + 2
+          params = params.merge(page: page_number)
+          responses << make_get_request(path, params: params, headers: headers)
+        end
+      end
+      unless responses.all?(&:success?)
+        raise ESI::Errors::PaginationError.new("Error paginating request", response: response,
+                                                                           responses: responses)
       end
 
-      all_items
+      all_items + responses.map(&:body).flatten
     end
 
     def make_delete_request(path, params: {}, headers: {})
-      res = url_encoded_connection.delete("/#{version}#{path}", params, headers)
-
-      raise_error(res) unless res.success?
-
-      res
+      params.delete_if { |_, v| v.nil? }
+      url_encoded_connection.delete("/#{version}#{path}", params, headers)
     end
 
     def make_get_request(path, params: {}, headers: {})
-      res = url_encoded_connection.get("/#{version}#{path}", params, headers)
-
-      raise_error(res) unless res.success?
-
-      res
+      params.delete_if { |_, v| v.nil? }
+      url_encoded_connection.get("/#{version}#{path}", params, headers)
     end
 
-    def make_post_request(path, payload: {}, headers: {})
-      res = json_encoded_connection.post("/#{version}#{path}", payload, headers)
-
-      raise_error(res) unless res.success?
-
-      res
+    def make_post_request(path, payload: {}, params: {}, headers: {})
+      params.delete_if { |_, v| v.nil? }
+      json_encoded_connection.post("/#{version}#{path}") do |req|
+        req.params = params
+        req.headers = req.headers.merge(headers)
+        req.body = payload.to_json
+      end
     end
 
-    def make_put_request(path, payload: {}, headers: {})
-      res = json_encoded_connection.put("/#{version}#{path}", payload, headers)
-
-      raise_error(res) unless res.success?
+    def make_put_request(path, payload: {}, params: {}, headers: {})
+      params.delete_if { |_, v| v.nil? }
+      json_encoded_connection.put("/#{version}#{path}") do |req|
+        req.params = params
+        req.headers = req.headers.merge(headers)
+        req.body = payload.to_json
+      end
+    end
 
-      res
+    def paginated?(headers)
+      headers["x-pages"] && headers["x-pages"].to_i > 1
     end
 
-    def paginated?(response)
-      response.headers["X-Pages"] && response.headers["X-Pages"].to_i <= 1
+    def normalize_headers(headers)
+      headers.transform_keys(&:downcase)
     end
 
     def raise_error(res)
-      raise (ERROR_MAPPING[res.status] || Error).new("(#{res.status}) #{res["error"]}", response: res)
+      raise (ERROR_MAPPING[res.status] || ESI::Errors::ClientError).new("(#{res.status}) #{res["error"]}",
+                                                                        response: res)
     end
 
     def url_encoded_connection
       @url_encoded_connection ||= Faraday.new(base_url, headers: default_headers) do |f|
         f.use :http_cache, **cache unless cache.empty?
-        f.request :url_encoded
-        f.request :retry, { exceptions: ESI_RETRY_EXCEPTIONS }
-        f.response :follow_redirects
+        f.request :retry, { exceptions: ESI_RETRY_EXCEPTIONS, max: 10, retry_statuses: [502, 503, 504] }
         f.response :json
+        f.adapter :typhoeus
       end
     end
 
@@ -212,14 +234,14 @@ module ESI
       @json_encoded_connection ||= Faraday.new(base_url, headers: default_headers) do |f|
         f.use :http_cache, **cache unless cache.empty?
         f.request :json
-        f.request :retry, { exceptions: ESI_RETRY_EXCEPTIONS }
-        f.response :follow_redirects
+        f.request :retry, { exceptions: ESI_RETRY_EXCEPTIONS, max: 10, retry_statuses: [502, 503, 504] }
         f.response :json
+        f.adapter :typhoeus
       end
     end
 
     def default_headers
-      { "User-Agent": user_agent }
+      { "User-Agent": user_agent, Accept: "application/json" }
     end
   end
 end

data/lib/esi/client/alliance.rb

@@ -13,7 +13,7 @@ module ESI
       # @esi_version v3
       # @esi_version v4
       #
-      # @param alliance_id [Integer,String] An EVE alliance ID
+      # @param alliance_id [Integer] An EVE alliance ID
       # @param params [Hash] Additional query string parameters
       # @param headers [Hash] Additional headers
       #
@@ -25,7 +25,7 @@ module ESI
       # @raise [ESI::Errors::GatewayTimeoutError] Gateway timeout
       #
       # @see https://esi.evetech.net/ui/#/Alliance/get_alliances_alliance_id
-      def get_alliance(alliance_id:, params: {}, headers: {})
+      def get_alliance(alliance_id:, headers: {}, params: {})
         get("/alliances/#{alliance_id}/", headers: headers, params: params)
       end
       alias get_alliances_alliance_id get_alliance
@@ -39,7 +39,7 @@ module ESI
       # @esi_version v1
       # @esi_version v2
       #
-      # @param alliance_id [Integer,String] An EVE alliance ID
+      # @param alliance_id [Integer] An EVE alliance ID
       # @param params [Hash] Additional query string parameters
       # @param headers [Hash] Additional headers
       #
@@ -50,7 +50,7 @@ module ESI
       # @raise [ESI::Errors::GatewayTimeoutError] Gateway timeout
       #
       # @see https://esi.evetech.net/ui/#/Alliance/get_alliances_alliance_id_corporations
-      def get_alliance_corporations(alliance_id:, params: {}, headers: {})
+      def get_alliance_corporations(alliance_id:, headers: {}, params: {})
         get("/alliances/#{alliance_id}/corporations/", headers: headers, params: params)
       end
       alias get_alliances_alliance_id_corporations get_alliance_corporations
@@ -60,7 +60,7 @@ module ESI
       # @esi_version legacy
       # @esi_version v1
       #
-      # @param alliance_id [Integer,String] An EVE alliance ID
+      # @param alliance_id [Integer] An EVE alliance ID
       # @param params [Hash] Additional query string parameters
       # @param headers [Hash] Additional headers
       #
@@ -72,7 +72,7 @@ module ESI
       # @raise [ESI::Errors::GatewayTimeoutError] Gateway timeout
       #
       # @see https://esi.evetech.net/ui/#/Alliance/get_alliances_alliance_id_icons
-      def get_alliance_icons(alliance_id:, params: {}, headers: {})
+      def get_alliance_icons(alliance_id:, headers: {}, params: {})
         get("/alliances/#{alliance_id}/icons/", headers: headers, params: params)
       end
       alias get_alliances_alliance_id_icons get_alliance_icons
@@ -96,7 +96,7 @@ module ESI
       # @raise [ESI::Errors::GatewayTimeoutError] Gateway timeout
       #
       # @see https://esi.evetech.net/ui/#/Alliance/get_alliances
-      def get_alliances(params: {}, headers: {})
+      def get_alliances(headers: {}, params: {})
         get("/alliances/", headers: headers, params: params)
       end
     end