incident-io 0.0.0.pre.alpha → 0.1.0

data/lib/incident_io/client.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module IncidentIo
+  # The API client. Handles auth, JSON, errors and retries.
+  #
+  #   client = IncidentIo::Client.new(api_key: ENV["INCIDENT_IO_API_KEY"])
+  #   client.incidents.show(id)                   # newest version of a resource
+  #   client.v1.incidents.list                    # a specific version
+  #   client.request(:get, "/v2/incidents/#{id}") # any endpoint, raw
+  class Client
+    include Resources::Accessors
+
+    DEFAULT_BASE_URL = "https://api.incident.io"
+    DEFAULT_TIMEOUT = 60
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_MAX_RETRIES = 2
+
+    # Safe to repeat: the server treats a repeated call the same as one.
+    IDEMPOTENT_METHODS = %i[get head put delete options].freeze
+    # Retried only when the request is idempotent.
+    RETRYABLE_STATUSES = [408, 500, 502, 503, 504].freeze
+    # 429 means the request was not processed, so it is always retried.
+    RATE_LIMIT_STATUS = 429
+
+    INITIAL_RETRY_DELAY = 0.5
+    MAX_RETRY_DELAY = 8.0
+    # If the API asks us to wait longer than this, raise instead.
+    MAX_RETRY_AFTER = 60.0
+
+    REQUEST_OPTIONS = %i[api_key timeout open_timeout max_retries headers].freeze
+
+    # The API's address, without a trailing slash
+    #
+    # @return [String]
+    attr_reader :base_url
+
+    # Seconds to wait for a response
+    #
+    # @return [Integer, Float]
+    attr_reader :timeout
+
+    # Seconds to wait for a connection
+    #
+    # @return [Integer, Float]
+    attr_reader :open_timeout
+
+    # How many times to retry after the first attempt
+    #
+    # @return [Integer]
+    attr_reader :max_retries
+
+    # Gets one debug line per attempt
+    #
+    # @return [Logger, nil]
+    attr_reader :logger
+
+    # Creates a client
+    #
+    # @param api_key [String] defaults to ENV["INCIDENT_IO_API_KEY"]
+    # @param base_url [String] defaults to ENV["INCIDENT_IO_BASE_URL"] or the public API
+    # @param timeout [Integer, Float] seconds to wait for a response
+    # @param open_timeout [Integer, Float] seconds to wait for a connection
+    # @param max_retries [Integer] retries after the first attempt
+    # @param logger [Logger, nil] gets one debug line per attempt
+    # @param user_agent [String, nil] added before the gem's own user agent
+    # @param transport [#call] see Transport::NetHTTP
+    # @raise [ConfigurationError] when there's no API key
+    def initialize(
+      api_key: ENV.fetch("INCIDENT_IO_API_KEY", nil),
+      base_url: ENV.fetch("INCIDENT_IO_BASE_URL", DEFAULT_BASE_URL),
+      timeout: DEFAULT_TIMEOUT,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      logger: nil,
+      user_agent: nil,
+      transport: Transport::NetHTTP.new
+    )
+      if api_key.nil? || api_key.to_s.empty?
+        raise ConfigurationError, "no API key: pass api_key: or set INCIDENT_IO_API_KEY"
+      end
+
+      @api_key = api_key.to_s
+      @base_url = base_url.to_s.chomp("/")
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @max_retries = max_retries
+      @logger = logger
+      @user_agent = [user_agent, "incident-io-ruby/#{VERSION} ruby/#{RUBY_VERSION}"].compact.join(" ")
+      @transport = transport
+    end
+
+    # Sends a request and returns the parsed body
+    #
+    # @param method [Symbol, String] the HTTP method, e.g. :get
+    # @param path [String] e.g. "/v2/incidents"
+    # @param query [Hash, nil] query parameters; nil values are left out
+    # @param body [Hash, nil] sent as JSON
+    # @param idempotent [Boolean, nil] whether 5xx and network errors may be
+    #   retried. Defaults to true for GET/HEAD/PUT/DELETE. Set true for a POST
+    #   that sends an `idempotency_key`.
+    # @param request_options [Hash] per-call overrides: api_key, timeout,
+    #   open_timeout, max_retries, headers
+    # @raise [APIError] for non-2xx responses
+    # @raise [APIConnectionError] when no response arrived
+    # @return [Hash, Array, String, nil] parsed JSON, other text (e.g. CSV),
+    #   or nil for an empty body
+    def request(method, path, query: nil, body: nil, idempotent: nil, request_options: {})
+      execute(method, path, query:, body:, idempotent:, request_options:).parsed
+    end
+
+    # Sends a request and returns the raw Response
+    #
+    # @param method [Symbol, String] the HTTP method, e.g. :get
+    # @param path [String] e.g. "/v2/incidents"
+    # @param query [Hash, nil] query parameters; nil values are left out
+    # @param body [Hash, nil] sent as JSON
+    # @param idempotent [Boolean, nil] whether 5xx and network errors may be
+    #   retried. Defaults to true for GET/HEAD/PUT/DELETE. Set true for a POST
+    #   that sends an `idempotency_key`.
+    # @param request_options [Hash] per-call overrides: api_key, timeout,
+    #   open_timeout, max_retries, headers
+    # @raise [APIError] for non-2xx responses
+    # @raise [APIConnectionError] when no response arrived
+    # @return [Response]
+    def execute(method, path, query: nil, body: nil, idempotent: nil, request_options: {})
+      method = method.to_s.downcase.to_sym
+      options = normalize_options(request_options)
+      idempotent = IDEMPOTENT_METHODS.include?(method) if idempotent.nil?
+      max_retries = options.fetch(:max_retries, @max_retries)
+
+      request = Request.new(
+        method:,
+        url: build_url(path, query),
+        headers: build_headers(options, json_body: !body.nil?),
+        body: body.nil? ? nil : JSON.generate(Util.serialize(body)),
+        timeout: options.fetch(:timeout, @timeout),
+        open_timeout: options.fetch(:open_timeout, @open_timeout)
+      )
+
+      with_retries(request, idempotent:, max_retries:)
+    end
+
+    # A lazy Pager over every item of a cursor-paginated list
+    #
+    # @param path [String] e.g. "/v2/incidents"
+    # @param items_key [String] key of the item array in the response,
+    #   e.g. "incidents"
+    # @param query [Hash, nil] query parameters; `after` sets the first cursor
+    # @param model [#from_api, nil] builds each item; raw hashes when nil
+    # @param request_options [Hash] see #request
+    # @return [Pager]
+    def paginate(path, items_key:, query: nil, model: nil, request_options: {})
+      Pager.new(self, path, items_key:, query:, model:, request_options:)
+    end
+
+    # A short description that leaves out the API key
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+
+    private
+
+    # Sends a request, retrying when that's safe and useful
+    #
+    # @param request [Request]
+    # @param idempotent [Boolean]
+    # @param max_retries [Integer]
+    # @raise [APIError, APIConnectionError] once retries run out
+    # @return [Response] a 2xx response
+    def with_retries(request, idempotent:, max_retries:)
+      attempt = 0
+      loop do
+        response = perform(request, attempt)
+        return response if response.success?
+
+        error = APIError.from_response(response)
+        delay = retry_delay(error, attempt, idempotent:, max_retries:)
+        raise error unless delay
+
+        log { "retrying #{request.method.upcase} after #{response.status} in #{delay.round(2)}s" }
+        sleep_for(delay)
+        attempt += 1
+      rescue APIConnectionError => e
+        raise e unless idempotent && attempt < max_retries
+
+        delay = backoff(attempt)
+        log { "retrying #{request.method.upcase} after #{e.class} in #{delay.round(2)}s" }
+        sleep_for(delay)
+        attempt += 1
+      end
+    end
+
+    # Sends one attempt through the transport and logs it
+    #
+    # @param request [Request]
+    # @param attempt [Integer] 0 for the first attempt
+    # @return [Response]
+    def perform(request, attempt)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = @transport.call(request)
+      log do
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        "#{request.method.upcase} #{redact(request.url)} -> #{response.status} " \
+          "(#{(elapsed * 1000).round}ms, attempt #{attempt + 1})"
+      end
+      response
+    end
+
+    # How long to wait before the next attempt
+    #
+    # @param error [APIError]
+    # @param attempt [Integer]
+    # @param idempotent [Boolean]
+    # @param max_retries [Integer]
+    # @return [Float, nil] seconds, or nil to give up
+    def retry_delay(error, attempt, idempotent:, max_retries:)
+      return nil if attempt >= max_retries
+
+      if error.status == RATE_LIMIT_STATUS
+        wait = error.retry_after
+        return backoff(attempt) if wait.nil?
+        return nil if wait > MAX_RETRY_AFTER
+
+        return wait
+      end
+
+      return nil unless idempotent && RETRYABLE_STATUSES.include?(error.status)
+
+      wait = error.retry_after
+      (wait && wait <= MAX_RETRY_AFTER) ? wait : backoff(attempt)
+    end
+
+    # Exponential backoff with up to 25% jitter: about 0.5s, 1s, 2s … 8s
+    #
+    # @param attempt [Integer]
+    # @return [Float] seconds
+    def backoff(attempt)
+      delay = [INITIAL_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY].min
+      delay * (1 - (rand * 0.25))
+    end
+
+    # Waits between attempts
+    #
+    # @param seconds [Integer, Float]
+    # @return [void]
+    def sleep_for(seconds)
+      sleep(seconds)
+    end
+
+    # The full URL for a path and query
+    #
+    # @param path [String]
+    # @param query [Hash, nil]
+    # @return [String]
+    def build_url(path, query)
+      path = "/#{path}" unless path.start_with?("/")
+      encoded = QueryEncoder.encode(query)
+      encoded.empty? ? "#{base_url}#{path}" : "#{base_url}#{path}?#{encoded}"
+    end
+
+    # The request headers, including auth
+    #
+    # @param options [Hash] normalized request options
+    # @param json_body [Boolean] whether a JSON body is sent
+    # @return [Hash{String => String}]
+    def build_headers(options, json_body:)
+      headers = {
+        "Authorization" => "Bearer #{options.fetch(:api_key, @api_key)}",
+        "Accept" => "application/json",
+        "User-Agent" => @user_agent
+      }
+      headers["Content-Type"] = "application/json" if json_body
+      extra = options[:headers]
+      extra ? headers.merge(extra) : headers
+    end
+
+    # Request options with symbol keys, checked for typos
+    #
+    # @param options [Hash, nil]
+    # @raise [ArgumentError] for unknown options
+    # @return [Hash{Symbol => Object}]
+    def normalize_options(options)
+      options = (options || {}).transform_keys(&:to_sym)
+      unknown = options.keys - REQUEST_OPTIONS
+      raise ArgumentError, "unknown request option#{"s" if unknown.size > 1}: #{unknown.join(", ")}" if unknown.any?
+
+      options
+    end
+
+    # The URL with any `token` query value hidden, for logs
+    #
+    # Some endpoints take a secret `token` in the query string.
+    #
+    # @param url [String]
+    # @return [String]
+    def redact(url)
+      url.gsub(/([?&]token=)[^&]*/, '\1[REDACTED]')
+    end
+
+    # Logs a debug line, built only when the logger wants it
+    #
+    # @yieldreturn [String] the message
+    # @return [void]
+    def log(&)
+      logger&.debug { "[incident-io] #{yield}" }
+    end
+  end
+end

data/lib/incident_io/errors.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module IncidentIo
+  # Base class for every error raised by this gem.
+  class Error < StandardError; end
+
+  # The client was set up wrongly, e.g. no API key.
+  class ConfigurationError < Error; end
+
+  # The request never got a response: DNS, TLS, refused or dropped connection.
+  class APIConnectionError < Error; end
+
+  # The request timed out while connecting, sending or reading.
+  class APITimeoutError < APIConnectionError; end
+
+  # The API answered with a non-2xx status. Fields come from the API's
+  # `ErrorResponse` body when there is one.
+  class APIError < Error
+    # One entry from `ErrorResponse.errors`.
+    Detail = Data.define(:code, :message, :field, :pointer, :metadata)
+
+    # `ErrorResponse.rate_limit`. `retry_after` is a Time.
+    RateLimit = Data.define(:name, :limit, :remaining, :retry_after)
+
+    # The HTTP status
+    #
+    # @return [Integer]
+    attr_reader :status
+
+    # The general kind of error, e.g. "validation_error"
+    #
+    # @return [String, nil]
+    attr_reader :type
+
+    # The API's ID for the request, useful when asking incident.io for help
+    #
+    # @return [String, nil]
+    attr_reader :request_id
+
+    # What went wrong, e.g. one entry per invalid field
+    #
+    # @return [Array<Detail>]
+    attr_reader :errors
+
+    # The rate limit that was hit, if any
+    #
+    # @return [RateLimit, nil]
+    attr_reader :rate_limit
+
+    # The response headers, with lower-case names
+    #
+    # @return [Hash{String => String}]
+    attr_reader :headers
+
+    # The parsed response body
+    #
+    # @return [Hash, String, nil]
+    attr_reader :body
+
+    # Builds the error class that matches a response's status
+    #
+    # @param response [Response]
+    # @return [APIError]
+    def self.from_response(response)
+      klass =
+        case response.status
+        when 400 then BadRequestError
+        when 401 then AuthenticationError
+        when 403 then PermissionDeniedError
+        when 404 then NotFoundError
+        when 408 then RequestTimeoutError
+        when 409 then ConflictError
+        when 422 then UnprocessableEntityError
+        when 429 then RateLimitError
+        when 500.. then InternalServerError
+        else APIError
+        end
+
+      klass.new(status: response.status, headers: response.headers, body: response.parsed)
+    end
+
+    # Creates an error from a response's parts
+    #
+    # @param status [Integer]
+    # @param headers [Hash{String => String}, nil]
+    # @param body [Object] the parsed response body
+    def initialize(status:, headers: nil, body: nil)
+      @status = status
+      @headers = headers || {}
+      @body = body
+
+      data = body.is_a?(Hash) ? body : {} #: Hash[String, untyped]
+      @type = data["type"]
+      @request_id = data["request_id"]
+      @errors = Array(data["errors"]).map { |e| build_detail(e) }
+      @rate_limit = build_rate_limit(data["rate_limit"])
+
+      super(build_message)
+    end
+
+    # How long the API asked us to wait before retrying
+    #
+    # Read from the Retry-After header, or the rate limit in the body.
+    #
+    # @return [Float, nil] seconds, or nil when the API gave no hint
+    def retry_after
+      header = headers["retry-after"]
+      if header
+        seconds = Float(header, exception: false)
+        return seconds if seconds
+
+        at = Util.parse_time(header, httpdate: true)
+        return [at - Time.now, 0.0].max if at
+      end
+
+      at = rate_limit&.retry_after
+      return nil unless at
+
+      [at - Time.now, 0.0].max
+    end
+
+    private
+
+    # Builds a Detail from one entry of `ErrorResponse.errors`
+    #
+    # @param error [Hash]
+    # @return [Detail]
+    def build_detail(error)
+      source = error["source"] || {}
+      Detail.new(
+        code: error["code"],
+        message: error["message"],
+        field: source["field"],
+        pointer: source["pointer"],
+        metadata: error["metadata"]
+      )
+    end
+
+    # Builds a RateLimit from `ErrorResponse.rate_limit`
+    #
+    # @param data [Object]
+    # @return [RateLimit, nil]
+    def build_rate_limit(data)
+      return nil unless data.is_a?(Hash)
+
+      RateLimit.new(
+        name: data["name"],
+        limit: data["limit"],
+        remaining: data["remaining"],
+        retry_after: Util.parse_time(data["retry_after"])
+      )
+    end
+
+    # The exception message, e.g. "422 validation_error: Must be a URL"
+    #
+    # @return [String]
+    def build_message
+      parts = ["#{status}#{" #{type}" if type}"]
+      detail = errors.map(&:message).compact.join("; ")
+      parts << detail unless detail.empty?
+      message = parts.join(": ")
+      request_id ? "#{message} (request_id: #{request_id})" : message
+    end
+  end
+
+  class BadRequestError < APIError; end
+  class AuthenticationError < APIError; end
+  class PermissionDeniedError < APIError; end
+  class NotFoundError < APIError; end
+  class RequestTimeoutError < APIError; end
+  class ConflictError < APIError; end
+  class UnprocessableEntityError < APIError; end
+  class RateLimitError < APIError; end
+  class InternalServerError < APIError; end
+end

data/lib/incident_io/model.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module IncidentIo
+  # Builds immutable model classes on top of `Data`.
+  #
+  #   Severity = IncidentIo::Model.define(id: :string, name: :string, rank: :integer)
+  #   Incident = IncidentIo::Model.define(
+  #     id: :string,
+  #     created_at: :time,
+  #     severity: -> { Severity },           # lazy, so models can refer to each other
+  #     tags: [:string],                     # array of a type
+  #     metadata: Model.map_of(:string)      # object with free-form keys
+  #   )
+  #
+  #   incident = Incident.from_api(json_hash)
+  #   incident.severity.name
+  #   incident[:field_added_later]           # read any field in the raw payload
+  #   incident.to_api                        # back to a JSON-ready hash
+  #
+  # Types: :string, :integer, :float, :boolean, :time, :date, :any, a model
+  # class, a Proc returning a type, `[type]` for arrays and `map_of(type)`.
+  #
+  # API fields whose names clash with core Ruby methods (e.g. `class`,
+  # `method`, `members`) get a trailing underscore: `class_`. Characters that
+  # can't appear in a method name become underscores:
+  # `private_alert.alert_created_v1` => `private_alert_alert_created_v1`.
+  module Model
+    MapOf = Data.define(:type)
+
+    # A type for objects with free-form keys, all with values of one type
+    #
+    # @param type [Object] the type of each value
+    # @return [MapOf]
+    def self.map_of(type)
+      MapOf.new(type: type)
+    end
+
+    # Builds a model class
+    #
+    # @param schema [Hash{Symbol => Object}] API field name => type
+    # @yield optional methods to add to the class, evaluated in the class
+    # @return [Class] a Data subclass with ClassMethods and InstanceMethods
+    def self.define(**schema, &block)
+      fields = schema.to_h { |api_name, type| [member_name(api_name), [api_name.to_s, type]] }.freeze
+      members = fields.keys
+
+      klass = Data.define(*members)
+      klass.extend(ClassMethods)
+      klass.include(InstanceMethods)
+      klass.instance_variable_set(:@fields, fields)
+
+      # Every field is optional: the API leaves some out and adds others.
+      # Fields that were passed, even as nil, are remembered so to_api sends
+      # them and leaves the rest out.
+      klass.define_method(:initialize) do |raw: nil, **attrs|
+        unknown = attrs.keys - members
+        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.join(", ")}" if unknown.any?
+
+        @_raw = raw.nil? ? nil : raw.dup.freeze
+        @_given = attrs.keys.freeze
+        super(**members.to_h { |m| [m, attrs[m]] })
+      end
+
+      klass.class_eval(&block) if block
+      klass
+    end
+
+    # The Ruby method name for an API field name
+    #
+    # @param api_name [String, Symbol]
+    # @return [Symbol]
+    def self.member_name(api_name)
+      name = api_name.to_s.gsub(/[^A-Za-z0-9_]/, "_").to_sym
+      reserved_names.include?(name) ? :"#{name}_" : name
+    end
+
+    # Method names that fields can't use, as models already define them
+    #
+    # @return [Array<Symbol>]
+    def self.reserved_names
+      @reserved_names ||= (Data.instance_methods + InstanceMethods.instance_methods + %i[initialize]).freeze
+    end
+
+    # Converts a parsed JSON value to a field's type
+    #
+    # @param type [Object] a type as described in the Model docs
+    # @param value [Object]
+    # @return [Object]
+    def self.coerce(type, value)
+      return nil if value.nil?
+
+      case type
+      when Proc then coerce(type.call, value)
+      when Array then Array(value).map { |v| coerce(type.first, v) }
+      when MapOf then value.to_h { |k, v| [k, coerce(type.type, v)] }
+      when :time then Util.parse_time(value) || value
+      when :date then parse_date(value)
+      when :float then value.is_a?(Integer) ? value.to_f : value
+      when ClassMethods then type.from_api(value)
+      else value
+      end
+    end
+
+    # Parses an ISO 8601 date, keeping the original value if it isn't one
+    #
+    # @param value [Object]
+    # @return [Date, Object]
+    def self.parse_date(value)
+      Date.iso8601(value.to_s)
+    rescue ArgumentError
+      value
+    end
+
+    # Added to every model class.
+    module ClassMethods
+      # The model's fields
+      #
+      # @return [Hash{Symbol => Array(String, Object)}] Ruby member name =>
+      #   [API field name, type]
+      def fields
+        @fields
+      end
+
+      # Builds a model from a parsed JSON hash
+      #
+      # Only the keys in the hash count as given, so a key the API left out
+      # stays out if the model is sent back, and a null stays null.
+      #
+      # @param hash [Hash, nil] a model is returned unchanged
+      # @return [Object, nil] the model, or nil for nil
+      def from_api(hash)
+        return nil if hash.nil?
+        return hash if hash.is_a?(self)
+
+        attrs = {} #: Hash[Symbol, untyped]
+        fields.each do |member, (api_name, type)|
+          attrs[member] = Model.coerce(type, hash[api_name]) if hash.key?(api_name)
+        end
+        new(raw: hash, **attrs)
+      end
+    end
+
+    # Added to every model instance.
+    module InstanceMethods
+      # The payload this model was built from
+      #
+      # @return [Hash, nil] nil if the model was built by hand
+      def raw
+        @_raw
+      end
+
+      # Reads a field by its API name from the raw payload
+      #
+      # Useful for fields the API has added since this gem was generated.
+      #
+      # @param key [String, Symbol]
+      # @return [Object, nil]
+      def [](key)
+        raw&.[](key.to_s)
+      end
+
+      # A copy with some fields changed
+      #
+      # Keeps which fields were given and the raw payload, which Data#with
+      # would lose.
+      #
+      # @param changes [Hash{Symbol => Object}]
+      # @return [Object] a model of the same class
+      def with(**changes)
+        return self if changes.empty?
+
+        model_class = _ = self.class
+        given = @_given.to_h { |member| [member, public_send(member)] }
+        model_class.new(raw: @_raw, **given, **changes)
+      end
+
+      # A hash ready for JSON, keyed by API field names
+      #
+      # Fields that were given are included, with nil sent as null. Fields
+      # that weren't given are left out.
+      #
+      # @return [Hash{String => Object}]
+      def to_api
+        model_class = _ = self.class #: ClassMethods
+        out = {} #: Hash[String, untyped]
+        model_class.fields.each do |member, (api_name, _type)|
+          out[api_name] = Util.serialize(public_send(member)) if @_given.include?(member)
+        end
+        out
+      end
+    end
+  end
+end