esirb 0.3.0 → 0.4.0

data/lib/esirb/path.rb

@@ -1,31 +1,107 @@
 # frozen_string_literal: true
 
+require "erb"
+require_relative "pagination"
+
 module Esirb
+  # An ESI endpoint path built by chaining method calls, sent with an HTTP verb method.
+  #
+  # Every call returns a new Path, so a partial path can be reused:
+  #
+  #   character = client.characters(123)
+  #   character.location.to_s # => "/characters/123/location"
+  #   character.skills.to_s   # => "/characters/123/skills"
   class Path
-    attr_reader :client, :string
+    include Pagination
+
+    VERBS = %i[get head delete post put patch].freeze
+
+    # Method names that become path segments. Conversion hooks like to_ary and to_str are left to Ruby.
+    SEGMENT_NAME = /\A(?!to_)[a-z][a-z0-9_]*\z/
+    SEGMENT_TYPES = [String, Symbol, Integer].freeze
+
+    # ESI segments with hyphens, which can't be Ruby method names. Calling the underscored name
+    # (client.freelance_jobs) sends the hyphenated segment. Segments keep their spelling across
+    # compatibility dates, so this covers every date. `rake esi:check_segments` compares it with
+    # ESI's OpenAPI spec for each date.
+    HYPHENATED_SEGMENTS = %w[
+      access-lists
+      compatibility-dates
+      freelance-jobs
+      mercenary-dens
+      mercenary-tactical-operations
+      military-campaigns
+      paragon-hub
+      recommended-fit
+      sovereignty-hubs
+    ].to_h { |segment| [segment.tr("-", "_"), segment] }.freeze
+
+    NO_BODY = Object.new.freeze
+    private_constant :NO_BODY
+
+    def self.segment_name?(name)
+      SEGMENT_NAME.match?(name.to_s)
+    end
+
+    attr_reader :client
+
+    def initialize(client:, segments: [])
+      raise ArgumentError, "client is required" if client.nil?
 
-    def initialize(client: nil)
       @client = client
-      @string = ""
+      @segments = segments.freeze
+      @path = segments.map { |segment| "/#{segment}" }.join.freeze
+      freeze
     end
 
-    %i[get head delete trace post put patch].each do |verb|
-      define_method verb do |**args|
-        client.connection.send(verb, @string) do |req|
-          req.params = args[:params] if args[:params]
-          req.body = args[:body] if args[:body]
-          req.headers = args[:headers] if args[:headers]
+    # get, head, delete, post, put and patch send the request and return the Faraday response.
+    # params: become the query string, body: is sent as JSON, and headers: are added to the
+    # client's defaults, replacing any with the same name.
+    VERBS.each do |verb|
+      define_method verb do |params: nil, body: NO_BODY, headers: nil|
+        client.connection.public_send(verb, to_s) do |req|
+          req.params.update(params) if params
+          req.body = body unless body.equal?(NO_BODY)
+          req.headers.update(headers) if headers
         end
       end
     end
 
-    def method_missing(m, *args, &block)
-      @string += "/#{m}"
-      args.each do |arg|
-        @string += "/#{arg}"
+    # The path, e.g. "/characters/123/location".
+    def to_s
+      @path
+    end
+
+    # Adds a segment and its path params to a copy of this path, exactly as given. Use it for
+    # segments that can't be reached by method name.
+    def segment(name, *params)
+      self.class.new(client:, segments: @segments + [name, *params].map { |value| encode(value) })
+    end
+
+    def method_missing(name, *params, **kwargs)
+      return super unless self.class.segment_name?(name)
+      if kwargs.any?
+        raise ArgumentError, "path segments only take positional params; pass query params to the HTTP verb as params:"
+      end
+
+      segment(HYPHENATED_SEGMENTS.fetch(name.to_s, name), *params)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      self.class.segment_name?(name) || super
+    end
+
+    private
+
+    def encode(value)
+      unless SEGMENT_TYPES.any? { |type| value.is_a?(type) }
+        raise ArgumentError, "path segments must be strings, symbols or integers, got #{value.inspect}"
       end
 
-      self
+      text = value.to_s
+      raise ArgumentError, "path segments can't be #{text.inspect}" if ["", ".", ".."].include?(text)
+
+      ERB::Util.url_encode(text)
     end
   end
 end

data/lib/esirb/raise_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "errors"
+
+module Esirb
+  # Raises esirb's errors in place of Faraday's: a ResponseError subclass for error statuses, and
+  # ConnectionFailed, TimeoutError or Error for failures with no response. The Faraday error is
+  # kept as the exception's cause.
+  class RaiseError < Faraday::Middleware
+    def call(env)
+      super
+    rescue Faraday::TimeoutError => e
+      raise Esirb::TimeoutError, e.message
+    rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise Esirb::ConnectionFailed, e.message
+    rescue Faraday::Error => e
+      raise Esirb::Error, e.message
+    end
+
+    def on_complete(env)
+      return unless env.status.to_i >= 400
+
+      raise ResponseError.for_status(env.status), env
+    end
+  end
+end

data/lib/esirb/rate_limit.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Esirb
+  # ESI's limits as reported on one response. A route uses either the per-group rate limit
+  # (X-Ratelimit-*) or the older error limit (X-ESI-Error-Limit-*), never both, so the other
+  # set of values is nil. See https://developers.eveonline.com/docs/services/esi/rate-limiting/
+  #
+  #   Esirb::RateLimit.new(response).remaining # => 1195
+  class RateLimit
+    WINDOW_UNITS = { "s" => 1, "m" => 60, "h" => 60 * 60 }.freeze
+    # With fewer errors than this left in the error limit window, esirb stops retrying, and with a
+    # cache store stops sending requests: running out blocks every ESI route until the window resets.
+    ERROR_LIMIT_FLOOR = 20
+    # Each reader and the header its whole-number value comes from.
+    HEADERS_BY_READER = {
+      remaining: "X-Ratelimit-Remaining",
+      used: "X-Ratelimit-Used",
+      error_limit_remaining: "X-ESI-Error-Limit-Remain",
+      error_limit_reset: "X-ESI-Error-Limit-Reset"
+    }.freeze
+
+    # group, limit (tokens per window), window (seconds), remaining and used (what this request
+    # cost) come from the rate limit; error_limit_remaining and error_limit_reset (seconds until
+    # the window resets) from the error limit.
+    attr_reader :group, :limit, :window, :remaining, :used, :error_limit_remaining, :error_limit_reset
+
+    # Takes a response (or anything with headers) or the headers themselves.
+    def initialize(source)
+      headers = Faraday::Utils::Headers.new.update(source.respond_to?(:headers) ? source.headers : source.to_h)
+
+      @group = headers["X-Ratelimit-Group"]
+      @limit, @window = parse_limit(headers["X-Ratelimit-Limit"])
+      HEADERS_BY_READER.each { |reader, header| instance_variable_set(:"@#{reader}", integer(headers[header])) }
+    end
+
+    # Whether the error limit is nearly used up. Routes on the newer rate limit don't send error
+    # limit headers, so this is false for them.
+    def error_limit_low?
+      !error_limit_remaining.nil? && error_limit_remaining < ERROR_LIMIT_FLOOR
+    end
+
+    private
+
+    # "150/15m" => [150, 900]
+    def parse_limit(value)
+      match = value.to_s.match(%r{\A(\d+)/(\d+)([smh])\z})
+      return [nil, nil] unless match
+
+      [match[1].to_i, match[2].to_i * WINDOW_UNITS.fetch(match[3])]
+    end
+
+    def integer(value)
+      Integer(value, exception: false) if value
+    end
+  end
+end

data/lib/esirb/retry.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "errors"
+
+module Esirb
+  # Retries requests that failed for reasons that usually clear up on their own, up to `retries`
+  # times in all, whatever the reason. Sits outside RaiseError, so it sees esirb's errors.
+  class Retry < Faraday::Middleware
+    # Usually transient: ESI tends to recover within a second or two.
+    TRANSIENT = [BadGateway, ServiceUnavailable, GatewayTimeout, TimeoutError, ConnectionFailed].freeze
+    # Safe to repeat. POST isn't, since it might do something twice, like sending a mail.
+    METHODS = %i[delete get head put].freeze
+    # Longest Retry-After worth waiting for, in seconds. Anything longer is raised for the app to handle.
+    MAX_WAIT = 10
+
+    # A method of its own, so specs can skip the wait.
+    def self.pause(seconds)
+      sleep(seconds)
+    end
+
+    def initialize(app, retries:)
+      super(app)
+      @retries = retries
+    end
+
+    # body is the original request body: after a failure, env.body holds the response's.
+    def call(env, body: env.body, attempt: 0)
+      env.body = body
+      @app.call(env)
+    rescue Error => e
+      wait = wait_for(env, e, attempt)
+      raise unless wait
+
+      self.class.pause(wait)
+      call(env, body:, attempt: attempt + 1)
+    end
+
+    private
+
+    # Seconds to wait before retrying, or nil to raise the error.
+    def wait_for(env, error, attempt)
+      return unless retry_allowed?(env, error, attempt)
+      return retry_after(error) if error.is_a?(TooManyRequests)
+      return unless TRANSIENT.any? { |error_class| error.is_a?(error_class) }
+
+      retry_after_header?(error) ? retry_after(error) : backoff(attempt)
+    end
+
+    def retry_allowed?(env, error, attempt)
+      attempt < @retries && METHODS.include?(env.method) && !error_limit_low?(error)
+    end
+
+    # Each failed retry is another error, so stop when the error limit is nearly used up.
+    def error_limit_low?(error)
+      error.is_a?(ResponseError) && error.rate_limit.error_limit_low?
+    end
+
+    # About 0.5s, then 1s, then 2s..., plus up to 50% so many clients don't retry in step.
+    def backoff(attempt)
+      0.5 * (2**attempt) * (1 + (rand * 0.5))
+    end
+
+    def retry_after_header?(error)
+      error.is_a?(ResponseError) && !error.headers["Retry-After"].nil?
+    end
+
+    # ESI's Retry-After, or nil if it's missing or too long to wait for.
+    def retry_after(error)
+      seconds = Float(error.headers["Retry-After"], exception: false) if retry_after_header?(error)
+      seconds if seconds && seconds <= MAX_WAIT
+    end
+  end
+end

data/lib/esirb/vary_by_authorization.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Esirb
+  # Adds Authorization to a response's Vary header when the request carried a token, so the
+  # ByVary cache strategy keys authenticated responses by token. ESI's Vary doesn't name it,
+  # which would let a cache store shared between clients serve one character's data to another.
+  class VaryByAuthorization < Faraday::Middleware
+    def on_complete(env)
+      return unless env.request_headers["Authorization"]
+
+      names = env.response_headers["Vary"].to_s.split(/[\s,]+/).reject(&:empty?)
+      return if names.include?("*") || names.any? { |name| name.casecmp?("Authorization") }
+
+      env.response_headers["Vary"] = [*names, "Authorization"].join(", ")
+    end
+  end
+end

data/lib/esirb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Esirb
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/esirb.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "esirb/version"
+require_relative "esirb/rate_limit"
+require_relative "esirb/errors"
+require_relative "esirb/configuration"
+require_relative "esirb/compatibility_date"
+require_relative "esirb/raise_error"
+require_relative "esirb/retry"
+require_relative "esirb/error_limit_guard"
+require_relative "esirb/vary_by_authorization"
 require_relative "esirb/client"
+require_relative "esirb/pagination"
 require_relative "esirb/path"
-
-module Esirb
-  class Error < StandardError; end
-end

data/lib/generators/esirb/install/install_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "esirb"
+
+module Esirb
+  module Generators
+    # rails generate esirb:install
+    #
+    # Writes config/initializers/esirb.rb with esirb's settings and a note on each. Rails finds this
+    # by its path, so esirb has no Rails dependency, and nothing here loads outside a Rails generator.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates config/initializers/esirb.rb with esirb's settings for ESI."
+
+      def create_initializer
+        template "esirb.rb.tt", "config/initializers/esirb.rb"
+      end
+
+      private
+
+      # For the User-Agent placeholder, e.g. "my-app" for a MyApp application.
+      def app_name
+        application = Rails.application if Rails.respond_to?(:application)
+        return "my-app" unless application
+
+        application.class.module_parent_name.underscore.dasherize
+      end
+
+      def defaults
+        Configuration::DEFAULTS
+      end
+    end
+  end
+end

data/lib/generators/esirb/install/templates/esirb.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Settings for esirb, the client for EVE Online's ESI API. Options passed to Esirb::Client.new
+# override these for that client. See https://github.com/sicks/esirb#configuration
+Esirb.configure do |config|
+  # CCP asks every app using ESI to identify itself, ideally with a contact email. esirb adds its
+  # own name after this.
+  config.user_agent = "<%= app_name %>/1.0 (you@example.com)"
+
+  # The ESI behavior to use. A newer date can change response shapes, so check your code against
+  # it before moving it. Dates are listed at https://esi.evetech.net/meta/compatibility-dates
+  config.compatibility_date = "<%= defaults[:compatibility_date] %>"
+
+  # Where to cache ESI responses, shared by every client. Without a store nothing is cached, and
+  # esirb can't pause requests when ESI's error limit is nearly used up. Keep entries for longer
+  # than a day, so static data like universe types can be revalidated cheaply, e.g.
+  # ActiveSupport::Cache.lookup_store(:solid_cache_store, namespace: "esirb", expires_in: 2.days)
+  config.cache_store = Rails.cache
+
+  # Seconds to wait for a response, and to open the connection.
+  # config.timeout = <%= defaults[:timeout] %>
+  # config.open_timeout = <%= defaults[:open_timeout] %>
+
+  # Times to retry a 502, 503 or 504, a timeout, a connection failure or a short 429, on GET, HEAD,
+  # PUT and DELETE. 0 turns retries off.
+  # config.retries = <%= defaults[:retries] %>
+
+  # ESI's tenant and response language.
+  # config.tenant = "<%= defaults[:tenant] %>"
+  # config.language = "<%= defaults[:language] %>"
+
+  # Add Faraday middleware, change the adapter or set other connection options, e.g. logging in
+  # development. headers: false keeps access tokens out of the log.
+  # config.faraday = ->(f) { f.response :logger, Rails.logger, headers: false } if Rails.env.development?
+end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: esirb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - sicks
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -37,32 +37,42 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
+description: A light client for EVE Online's ESI API. Build any endpoint's path from
+  method calls, with caching, retries, rate and error limit handling, and pagination
+  helpers built in.
 email:
 - esirb@sicks.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/esirb.rb
 - lib/esirb/client.rb
+- lib/esirb/compatibility_date.rb
+- lib/esirb/configuration.rb
+- lib/esirb/error_limit_guard.rb
+- lib/esirb/errors.rb
+- lib/esirb/pagination.rb
 - lib/esirb/path.rb
+- lib/esirb/raise_error.rb
+- lib/esirb/rate_limit.rb
+- lib/esirb/retry.rb
+- lib/esirb/vary_by_authorization.rb
 - lib/esirb/version.rb
-- sig/esirb.rbs
+- lib/generators/esirb/install/install_generator.rb
+- lib/generators/esirb/install/templates/esirb.rb.tt
 homepage: https://github.com/sicks/esirb
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/sicks/esirb
   source_code_uri: https://github.com/sicks/esirb
   changelog_uri: https://github.com/sicks/esirb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sicks/esirb/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +80,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -79,5 +89,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.15
 specification_version: 4
-summary: Ruby interface for Eve Online's Swagger API
+summary: Ruby client for EVE Online's ESI API
 test_files: []

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,8 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes

data/.ruby-version

@@ -1 +0,0 @@
-ruby-3.4.7

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]

data/sig/esirb.rbs

@@ -1,4 +0,0 @@
-module Esirb
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end