zaius 0.1.0

data/lib/zaius/util.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Zaius
+  module Util
+    # Options that a user is allowed to specify.
+    OPTS_USER_SPECIFIED = Set[
+      :api_key,
+    ].freeze
+
+    # Options that should be copyable from one ZaiusObject to another
+    # including options that may be internal.
+    OPTS_COPYABLE = (
+      OPTS_USER_SPECIFIED + Set[:api_base]
+    ).freeze
+
+    # Options that should be persisted between API requests. This includes
+    # client, which is an object containing an HTTP client to reuse.
+    OPTS_PERSISTABLE = (
+      OPTS_USER_SPECIFIED + Set[:client]
+    ).freeze
+
+    def self.objects_to_ids(h)
+      case h
+      when APIResource
+        h.id
+      when Hash
+        res = {}
+        h.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
+        res
+      when Array
+        h.map { |v| objects_to_ids(v) }
+      else
+        h
+      end
+    end
+
+    def self.object_classes
+      @object_classes ||= {
+        ListObject::OBJECT_NAME => ListObject,
+        Subscription::OBJECT_NAME => Subscription,
+      }
+    end
+
+    # Converts a hash of fields or an array of hashes into a +ZaiusObject+ or
+    # array of +ZaiusObject+s. These new objects will be created as a concrete
+    # type as dictated by their `object` field (e.g. an `object` value of
+    # `charge` would create an instance of +Charge+), but if `object` is not
+    # present or of an unknown type, the newly created instance will fall back
+    # to being a +ZaiusObject+.
+    #
+    # ==== Attributes
+    #
+    # * +data+ - Hash of fields and values to be converted into a ZaiusObject.
+    # * +opts+ - Options for +ZaiusObject+ like an API key that will be reused
+    #   on subsequent API calls.
+    def self.convert_to_zaius_object(data, opts = {})
+      case data
+      when Array
+        data.map { |i| convert_to_zaius_object(i, opts) }
+      when Hash
+        # Try converting to a known object class.  If none available, fall back to generic ZaiusObject
+        object_classes.fetch(data[:object], ZaiusObject).construct_from(data, opts)
+      else
+        data
+      end
+    end
+
+    def self.log_info(message, data = {})
+      if !Zaius.logger.nil? ||
+         !Zaius.log_level.nil? && Zaius.log_level <= Zaius::LEVEL_INFO
+        log_internal(message, data, color: :cyan, out: $stderr)
+      end
+    end
+
+    def self.log_debug(message, data = {})
+      if !Zaius.logger.nil? ||
+         !Zaius.log_level.nil? && Zaius.log_level <= Zaius::LEVEL_DEBUG
+        log_internal(message, data, color: :cyan, out: $stderr)
+      end
+    end
+
+    def self.log_error(message, data = {})
+      if !Zaius.logger.nil? ||
+         !Zaius.log_level.nil? && Zaius.log_level <= Zaius::LEVEL_ERROR
+        log_internal(message, data, color: :cyan, out: $stderr)
+      end
+    end
+
+    def self.symbolize_names(object)
+      case object
+      when Hash
+        new_hash = {}
+        object.each do |key, value|
+          key = (begin
+                   key.to_sym
+                 rescue StandardError
+                   key
+                 end) || key
+          new_hash[key] = symbolize_names(value)
+        end
+        new_hash
+      when Array
+        object.map { |value| symbolize_names(value) }
+      else
+        object
+      end
+    end
+
+    # Encodes a hash of parameters in a way that's suitable for use as query
+    # parameters in a URI or as form parameters in a request body. This mainly
+    # involves escaping special characters from parameter keys and values (e.g.
+    # `&`).
+    def self.encode_parameters(params)
+      Util.flatten_params(params)
+          .map { |k, v| "#{url_encode(k)}=#{url_encode(v)}" }.join("&")
+    end
+
+    # Encodes a string in a way that makes it suitable for use in a set of
+    # query parameters in a URI or in a set of form parameters in a request
+    # body.
+    def self.url_encode(key)
+      CGI.escape(key.to_s).
+        # Don't use strict form encoding by changing the square bracket control
+        # characters back to their literals. This is fine by the server, and
+        # makes these parameter strings easier to read.
+        gsub("%5B", "[").gsub("%5D", "]")
+    end
+
+    def self.flatten_params(params, parent_key = nil)
+      result = []
+
+      # do not sort the final output because arrays (and arrays of hashes
+      # especially) can be order sensitive, but do sort incoming parameters
+      params.each do |key, value|
+        calculated_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s
+        if value.is_a?(Hash)
+          result += flatten_params(value, calculated_key)
+        elsif value.is_a?(Array)
+          result += flatten_params_array(value, calculated_key)
+        else
+          result << [calculated_key, value]
+        end
+      end
+
+      result
+    end
+
+    def self.flatten_params_array(value, calculated_key)
+      result = []
+      value.each_with_index do |elem, i|
+        if elem.is_a?(Hash)
+          result += flatten_params(elem, "#{calculated_key}[#{i}]")
+        elsif elem.is_a?(Array)
+          result += flatten_params_array(elem, calculated_key)
+        else
+          result << ["#{calculated_key}[#{i}]", elem]
+        end
+      end
+      result
+    end
+
+    def self.normalize_id(id)
+      if id.is_a?(Hash) # overloaded id
+        params_hash = id.dup
+        id = params_hash.delete(:id)
+      else
+        params_hash = {}
+      end
+      [id, params_hash]
+    end
+
+    # The secondary opts argument can either be a string or hash
+    # Turn this value into an api_key and a set of headers
+    def self.normalize_opts(opts)
+      case opts
+      when String
+        { api_key: opts }
+      when Hash
+        check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key)
+        opts.clone
+      else
+        raise TypeError, "normalize_opts expects a string or a hash"
+      end
+    end
+
+    def self.check_string_argument!(key)
+      raise TypeError, "argument must be a string" unless key.is_a?(String)
+      key
+    end
+
+    def self.check_api_key!(key)
+      raise TypeError, "api_key must be a string" unless key.is_a?(String)
+      key
+    end
+
+    # Normalizes header keys so that they're all lower case and each
+    # hyphen-delimited section starts with a single capitalized letter. For
+    # example, `request-id` becomes `Request-Id`. This is useful for extracting
+    # certain key values when the user could have set them with a variety of
+    # diffent naming schemes.
+    def self.normalize_headers(headers)
+      headers.each_with_object({}) do |(k, v), new_headers|
+        k = k.to_s.tr("_", "-") if k.is_a?(Symbol)
+        k = k.split("-").reject(&:empty?).map(&:capitalize).join("-")
+
+        new_headers[k] = v
+      end
+    end
+
+    # Constant time string comparison to prevent timing attacks
+    # Code borrowed from ActiveSupport
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack "C#{a.bytesize}"
+
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res.zero?
+    end
+
+    #
+    # private
+    #
+
+    COLOR_CODES = {
+      black:   0, light_black:   60,
+      red:     1, light_red:     61,
+      green:   2, light_green:   62,
+      yellow:  3, light_yellow:  63,
+      blue:    4, light_blue:    64,
+      magenta: 5, light_magenta: 65,
+      cyan:    6, light_cyan:    66,
+      white:   7, light_white:   67,
+      default: 9,
+    }.freeze
+    private_constant :COLOR_CODES
+
+    # Uses an ANSI escape code to colorize text if it's going to be sent to a
+    # TTY.
+    def self.colorize(val, color, isatty)
+      return val unless isatty
+
+      mode = 0 # default
+      foreground = 30 + COLOR_CODES.fetch(color)
+      background = 40 + COLOR_CODES.fetch(:default)
+
+      "\033[#{mode};#{foreground};#{background}m#{val}\033[0m"
+    end
+    private_class_method :colorize
+
+    # Turns an integer log level into a printable name.
+    def self.level_name(level)
+      level
+    end
+    private_class_method :level_name
+
+    # TODO: Make these named required arguments when we drop support for Ruby
+    # 2.0.
+    def self.log_internal(message, data = {}, color: nil, level: nil, logger: nil, out: nil)
+      data_str = data.reject { |_k, v| v.nil? }
+                     .map do |(k, v)|
+        format("%s=%s", colorize(k, color, logger.nil? && !out.nil? && out.isatty), wrap_logfmt_value(v))
+      end.join(" ")
+
+      if !logger.nil?
+        # the library's log levels are mapped to the same values as the
+        # standard library's logger
+        logger.log(level,
+                   format("message=%s %s", wrap_logfmt_value(message), data_str))
+      elsif out.isatty
+        out.puts format("%s %s %s", nil, message, data_str)
+      else
+        out.puts format("message=%s level=%s %s", wrap_logfmt_value(message), level_name(level), data_str)
+      end
+    end
+    private_class_method :log_internal
+
+    # Wraps a value in double quotes if it looks sufficiently complex so that
+    # it can be read by logfmt parsers.
+    def self.wrap_logfmt_value(val)
+      # If value is any kind of number, just allow it to be formatted directly
+      # to a string (this will handle integers or floats).
+      return val if val.is_a?(Numeric)
+
+      # Hopefully val is a string, but protect in case it's not.
+      val = val.to_s
+
+      if %r{[^\w\-/]} =~ val
+        # If the string contains any special characters, escape any double
+        # quotes it has, remove newlines, and wrap the whole thing in quotes.
+        format(%("%s"), val.gsub('"', '\"').delete("\n"))
+      else
+        # Otherwise use the basic value if it looks like a standard set of
+        # characters (and allow a few special characters like hyphens, and
+        # slashes)
+        val
+      end
+    end
+    private_class_method :wrap_logfmt_value
+  end
+end

data/lib/zaius/version.rb

@@ -0,0 +1,3 @@
+module Zaius
+  VERSION = "0.1.0".freeze
+end

data/lib/zaius/zaius_client.rb

@@ -0,0 +1,273 @@
+module Zaius
+  class ZaiusClient
+    attr_accessor :conn
+
+    # Initializes a new ZaiusClient. Expects a Faraday connection object, and
+    # uses a default connection unless one is passed.
+    def initialize(conn = nil)
+      self.conn = conn || self.class.default_conn
+    end
+
+    def self.default_client
+      Thread.current[:zaius_client_default_client] ||= ZaiusClient.new(default_conn)
+    end
+
+    def self.active_client
+      Thread.current[:zaius_client] || default_client
+    end
+
+    # A default Faraday connection to be used when one isn't configured. This
+    # object should never be mutated, and instead instantiating your own
+    # connection and wrapping it in a ZaiusClient object should be preferred.
+    def self.default_conn
+      # We're going to keep connections around so that we can take advantage
+      # of connection re-use, so make sure that we have a separate connection
+      # object per thread.
+      Thread.current[:zaius_client_default_conn] ||= begin
+        conn = Faraday.new do |c|
+          c.use Faraday::Request::Multipart
+          c.use Faraday::Request::UrlEncoded
+          c.use Faraday::Response::RaiseError
+          c.adapter Faraday.default_adapter
+        end
+
+        conn
+      end
+    end
+
+    def request_headers(api_key, method)
+      user_agent = "Zaius/v1 RubyBindings/#{Zaius::VERSION}"
+
+      headers = {
+        "User-Agent" => user_agent,
+        "x-api-key" => api_key,
+        "Content-Type" => "application/x-www-form-urlencoded",
+      }
+
+      headers
+    end
+
+    def execute_request(method, path,
+                        api_base: nil, api_key: nil, headers: {}, params: {})
+
+      api_base ||= Zaius.api_base
+      api_key ||= Zaius.api_key
+
+      check_api_key!(api_key)
+
+      url = api_url(path, api_base)
+
+      body = nil
+      query_params = nil
+
+      case method.to_s.downcase.to_sym
+      when :get, :head, :delete
+        query_params = params
+      else
+        body = params.to_json
+      end
+
+      # This works around an edge case where we end up with both query
+      # parameters in `query_params` and query parameters that are appended
+      # onto the end of the given path. In this case, Faraday will silently
+      # discard the URL's parameters which may break a request.
+      #
+      # Here we decode any parameters that were added onto the end of a path
+      # and add them to `query_params` so that all parameters end up in one
+      # place and all of them are correctly included in the final request.
+      # u = URI.parse(path)
+      # unless u.query.nil?
+      #   query_params ||= {}
+      #   query_params = Hash[URI.decode_www_form(u.query)].merge(query_params)
+
+      #   # Reset the path minus any query parameters that were specified.
+      #   path = u.path
+      # end
+
+      headers = request_headers(api_key, method)
+                .update(headers)
+
+      # stores information on the request we're about to make so that we don't
+      # have to pass as many parameters around for logging.
+      context = RequestLogContext.new
+      context.api_key         = api_key
+      context.body            = body
+      context.method          = method
+      context.path            = path
+      context.query_params    = query_params ? Util.encode_parameters(query_params) : nil
+
+      http_resp = execute_request_with_rescues(api_base, context) do
+        conn.run_request(method, url, body, headers) do |req|
+          req.params = query_params unless query_params.nil?
+        end
+      end
+
+      begin
+        resp = ZaiusResponse.from_faraday_response(http_resp)
+      rescue JSON::ParserError
+        raise general_api_error(http_resp.status, http_resp.body)
+      end
+
+      # Allows ZaiusClient#request to return a response object to a caller.
+      @last_response = resp
+      [resp, api_key]
+    end
+
+    def execute_request_with_rescues(api_base, context)
+      num_retries = 0
+      begin
+        request_start = Time.now
+        log_request(context, num_retries)
+        resp = yield
+        context = context.dup_from_response(resp)
+        log_response(context, request_start, resp.status, resp.body)
+
+      # We rescue all exceptions from a request so that we have an easy spot to
+      # implement our retry logic across the board. We'll re-raise if it's a type
+      # of exception that we didn't expect to handle.
+      rescue StandardError => e
+        # If we modify context we copy it into a new variable so as not to
+        # taint the original on a retry.
+        error_context = context
+
+        if e.respond_to?(:response) && e.response
+          error_context = context.dup_from_response(e.response)
+          log_response(error_context, request_start,
+                       e.response[:status], e.response[:body])
+        else
+          log_response_error(error_context, request_start, e)
+        end
+
+        case e
+        when Faraday::ClientError
+          if e.response
+            handle_error_response(e.response, error_context)
+          else
+            handle_network_error(e, error_context, num_retries, api_base)
+          end
+
+        # Only handle errors when we know we can do so, and re-raise otherwise.
+        # This should be pretty infrequent.
+        else
+          raise
+        end
+      end
+
+      resp
+    end
+
+    def handle_error_response(http_resp, context)
+      begin
+        resp = ZaiusResponse.from_faraday_hash(http_resp)
+        error_data = resp.data[:title]
+
+        raise ZaiusError, "Indeterminate error" if resp.data[:title].nil?
+      rescue JSON::ParserError, ZaiusError
+        raise general_api_error(http_resp[:status], http_resp[:body])
+      end
+
+      error = specific_api_error(resp, error_data, context)
+
+      error.response = resp
+      raise(error)
+    end
+
+    def general_api_error(status, body)
+      ZaiusError.new("Invalid response object from API: #{body.inspect} " \
+                   "(HTTP response code was #{status})",
+                   http_status: status, http_body: body)
+    end
+
+    def specific_api_error(response, error_data, context)
+      response_data = response.data
+
+      APIError.new(title: response_data[:title], http_status: response.http_status, detail: response_data[:detail])
+    end
+
+    def log_response(context, request_start, status, body)
+      Util.log_info("Response from Zaius",
+                    account: context.account,
+                    api_version: context.api_version,
+                    elapsed: Time.now - request_start,
+                    method: context.method,
+                    path: context.path,
+                    request_id: context.request_id,
+                    url: context.url,
+                    status: status)
+      Util.log_debug("Response details",
+                     body: body,
+                      request_id: context.request_id)
+    end
+
+    def log_request(context, num_retries)
+      Util.log_info("Request to Zaius",
+                    account: context.account,
+                    api_version: context.api_version,
+                    method: context.method,
+                    num_retries: num_retries,
+                    path: context.path)
+      Util.log_debug("Request details",
+                     body: context.body,
+                     query_params: context.query_params)
+    end
+    private :log_request
+
+    def log_response_error(context, request_start, e)
+      Util.log_error("Request error",
+                     elapsed: Time.now - request_start,
+                     error_message: e.message,
+                      method: context.method,
+                     path: context.path)
+    end
+
+    def api_url(url = "", api_base = nil)
+      (api_base || Zaius.api_base) + url
+    end
+
+    def check_api_key!(api_key)
+      unless api_key
+        raise AuthenticationError, "No API key provided. " \
+          'Set your API key using "Zaius.api_key = <API-KEY>". '
+      end
+
+      return unless api_key =~ /\s/
+
+      raise AuthenticationError, "Your API key is invalid, as it contains whitespace."
+    end
+  end
+
+  # RequestLogContext stores information about a request that's begin made so
+  # that we can log certain information. It's useful because it means that we
+  # don't have to pass around as many parameters.
+  class RequestLogContext
+    attr_accessor :body
+    attr_accessor :account
+    attr_accessor :api_key
+    attr_accessor :api_version
+    attr_accessor :method
+    attr_accessor :path
+    attr_accessor :query_params
+    attr_accessor :request_id
+    attr_accessor :url
+
+    # The idea with this method is that we might want to update some of
+    # context information because a response that we've received from the API
+    # contains information that's more authoritative than what we started
+    # with for a request.
+    def dup_from_response(resp)
+      return self if resp.nil?
+
+      # Faraday's API is a little unusual. Normally it'll produce a response
+      # object with a `headers` method, but on error what it puts into
+      # `e.response` is an untyped `Hash`.
+      headers = if resp.is_a?(Faraday::Response)
+                  resp.headers
+                else
+                  resp[:headers]
+                end
+
+      context = dup
+      context
+    end
+  end
+end