hyperion_http 0.1.2

data/lib/hyperion/aux/logger.rb

@@ -0,0 +1,54 @@
+class Hyperion
+  module Logger
+    class << self
+      attr_accessor :level
+    end
+
+    def logger
+      rails_logger_available? ? Rails.logger : default_logger
+    end
+
+    def with_request_logging(route, uri, headers)
+      log_request_start(route, uri, headers)
+      start = Time.now
+      begin
+        yield
+      ensure
+        stop = Time.now
+        log_request_end(((stop - start) * 1000).round)
+      end
+    end
+
+    def log_stub(rule)
+      mr = rule.mimic_route
+      logger.debug "Stubbed #{mr.method.to_s.upcase} #{mr.path}"
+      log_headers(rule.headers)
+    end
+
+    private
+
+    def log_request_start(route, uri, headers)
+      logger.debug "Requesting #{route.method.to_s.upcase} #{uri}"
+      log_headers(headers)
+    end
+
+    def log_request_end(ms)
+      logger.debug "Completed in #{ms}ms"
+      logger.debug ''
+    end
+
+    def rails_logger_available?
+      Kernel.const_defined?(:Rails) && !Rails.logger.nil?
+    end
+
+    def default_logger
+      logger = ::Logger.new($stdout)
+      logger.level = Hyperion::Logger.level || ::Logger::DEBUG
+      logger
+    end
+
+    def log_headers(headers)
+      headers.each_pair { |k, v| logger.debug "    #{k}: #{v}" unless k == 'Expect' }
+    end
+  end
+end

data/lib/hyperion/aux/typho.rb

@@ -0,0 +1,9 @@
+class Hyperion
+  # all Typhoeus interation goes through this module
+  # for maintenance and mocking purposes
+  class Typho
+    def self.request(uri, options={})
+      Typhoeus::Request.new(uri, options).run
+    end
+  end
+end

data/lib/hyperion/aux/util.rb

@@ -0,0 +1,18 @@
+require 'hyperion/aux/bug_error'
+
+class Hyperion
+  class Util
+    def self.nil_if_error
+      begin
+        yield
+      rescue StandardError
+        return nil
+      end
+    end
+
+    def self.guard_param(value, what, expected_type=nil, &pred)
+      pred ||= proc { |x| x.is_a?(expected_type) }
+      pred.call(value) or fail BugError, "You passed me #{value.inspect}, which is not #{what}"
+    end
+  end
+end

data/lib/hyperion/aux/version.rb

@@ -0,0 +1,3 @@
+class Hyperion
+  VERSION = '0.1.2'
+end

data/lib/hyperion/formats.rb

@@ -0,0 +1,69 @@
+require 'oj'
+require 'stringio'
+require 'hyperion/aux/logger'
+require 'abstractivator/enum'
+
+class Hyperion
+  module Formats
+    # Serializes and deserializes the supported formats.
+    # This is done as gracefully as possible.
+
+    include Hyperion::Logger
+
+    define_enum :Known, :json, :protobuf
+
+    def write(obj, format)
+      return obj if obj.is_a?(String) || obj.nil? || format.nil?
+
+      case Formats.get_from(format)
+      when :json; write_json(obj)
+      when :protobuf; obj
+      else; fail "Unsupported format: #{format}"
+      end
+    end
+
+    def read(bytes, format)
+      return nil if bytes.nil?
+      return bytes if format.nil?
+
+      case Formats.get_from(format)
+      when :json; read_json(bytes)
+      when :protobuf; bytes
+      else; fail "Unsupported format: #{format}"
+      end
+    end
+
+    def self.get_from(x)
+      x.respond_to?(:format) ? x.format : x
+    end
+
+    private
+
+    def write_json(obj)
+      Oj.dump(obj, oj_options)
+    end
+
+    def read_json(bytes)
+      begin
+        Oj.compat_load(bytes, oj_options)
+      rescue Oj::ParseError => e
+        logger.error e.message
+        bytes
+      end
+    end
+
+    def oj_options
+      {
+          mode: :compat,
+          time_format: :xmlschema,  # xmlschema == iso8601
+          use_to_json: false,
+          second_precision: 3
+      }
+    end
+
+    def get_oj_line_and_col(e)
+      m = e.message.match(/at line (?<line>\d+), column (?<col>\d+)/)
+      m ? [m[:line].to_i, m[:col].to_i] : nil
+    end
+  end
+end

data/lib/hyperion/headers.rb

@@ -0,0 +1,43 @@
+require 'hyperion/formats'
+
+class Hyperion
+  module Headers
+    # constructs and destructures HTTP headers
+
+    def route_headers(route)
+      headers = {}
+      rd = route.response_descriptor
+      pd = route.payload_descriptor
+      headers['Expect'] = 'x' # this overrides default libcurl behavior.
+                              # see http://devblog.songkick.com/2012/11/27/a-second-here-a-second-there/
+                              # the value has to be non-empty or else it is ignored
+      if rd
+        headers['Accept'] = "application/vnd.#{Hyperion.config.vendor_string}.#{short_mimetype(rd)}"
+      end
+      if pd
+        headers['Content-Type'] = content_type_for(pd.format)
+      end
+      headers
+    end
+
+    def short_mimetype(response_descriptor)
+      x = response_descriptor
+      "#{x.type}-v#{x.version}+#{x.format}"
+    end
+
+    ContentTypes = [[:json, 'application/json'],
+                    [:protobuf, 'application/x-protobuf']]
+
+    def content_type_for(format)
+      format = Hyperion::Formats.get_from(format)
+      ct = ContentTypes.detect{|x| x.first == format}
+      ct ? ct.last : 'application/octet-stream'
+    end
+
+    def format_for(content_type)
+      ct = ContentTypes.detect{|x| x.last == content_type}
+      fail "Unsupported content type: #{content_type}" unless ct
+      ct.first
+    end
+  end
+end

data/lib/hyperion/hyperion.rb

@@ -0,0 +1,79 @@
+require 'hyperion/headers'
+require 'hyperion/formats'
+require 'hyperion/aux/logger'
+require 'hyperion/aux/typho'
+require 'hyperion/result_handling/result_maker'
+
+class Hyperion
+  include Headers
+  include Formats
+  include Logger
+
+  Config = Struct.new(:vendor_string)
+
+  # @param route [RestRoute]
+  # @param body [String] the body to send with POST or PUT
+  # @param additional_headers [Hash] headers to send in addition to the ones
+  #   already determined by the route. Example: +{'User-Agent' => 'Mozilla/5.0'}+
+  # @yield [result] yields the result if a block is provided
+  # @yieldparam [HyperionResult]
+  # @return [HyperionResult, Object] If a block is provided, returns the block's
+  #   return value; otherwise, returns the result.
+  def self.request(route, body=nil, additional_headers={}, &block)
+    self.new(route).request(body, additional_headers, &block)
+  end
+
+  # @private
+  def initialize(route)
+    @route = route
+  end
+
+  # @private
+  def request(body=nil, additional_headers={}, &dispatch)
+    uri = transform_uri(route.uri).to_s
+    with_request_logging(route, uri, route_headers(route)) do
+      typho_result = Typho.request(uri,
+                                   method: route.method,
+                                   headers: build_headers(additional_headers),
+                                   body: write(body, route.payload_descriptor))
+      hyperion_result_for(typho_result, dispatch)
+    end
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  private
+
+  attr_reader :route
+
+  def self.config
+    @config ||= Config.new('indigobio-ascent')
+  end
+
+  def build_headers(additional_headers)
+    route_headers(route).merge(additional_headers)
+  end
+
+  def hyperion_result_for(typho_result, dispatch)
+    result_maker = ResultMaker.new(route)
+    if dispatch
+      # callcc allows control to "jump" back here when the first predicate matches
+      callcc do |cont|
+        dispatch.call(result_maker.make(typho_result, cont))
+      end
+    else
+      result_maker.make(typho_result)
+    end
+  end
+
+  def transform_uri(uri)
+    Hyperion.send(:transform_uri, uri)
+  end
+
+  # give Hyperion::Test a shot at changing the uri for stubbing purposes
+  def self.transform_uri(uri)
+    uri
+  end
+end

data/lib/hyperion/requestor.rb

@@ -0,0 +1,88 @@
+require 'hyperion'
+
+class Hyperion
+  module Requestor
+
+    # @param [RestRoute] route The route to request
+    # @option opts [Object] :body The payload to POST/PUT. Usually a Hash or Array.
+    # @option opts [Hash<predicate, transformer>] :also_handle Additional handlers to
+    #   use besides the default handlers. A predicate is an integer HTTP code, an
+    #   integer Range of HTTP codes, a HyperionStatus enumeration value,
+    #   or a predicate proc. A transformer is a procedure which accepts a
+    #   HyperionResult and returns the final value to return from `request`
+    # @option opts [Proc] :render A transformer, usually a proc returned by
+    #   `as` or `as_many`. Only called on HTTP 200.
+    # @yield [rendered] Yields to allow an additional transformation.
+    #   Only called on HTTP 200.
+    def request(route, opts={}, &project)
+      Hyperion::Util.guard_param(route, 'a RestRoute', RestRoute)
+      Hyperion::Util.guard_param(opts, 'an options hash', Hash)
+
+      body = opts[:body]
+      additional_handler_hash = opts[:also_handle] || {}
+      render = opts[:render] || Proc.identity
+      project = project || Proc.identity
+
+      Hyperion.request(route, body) do |result|
+        all_handlers = [hash_handler(additional_handler_hash),
+                        handler_from_including_class,
+                        built_in_handler(project, render)]
+
+        all_handlers.each { |handlers| handlers.call(result) }
+        fallthrough(result)
+      end
+    end
+
+    private
+
+    def hash_handler(hash)
+      proc do |result|
+        hash.each_pair do |condition, consequent|
+          result.when(condition) { Proc.loose_call(consequent, [result]) }
+        end
+      end
+    end
+
+    def handler_from_including_class
+      respond_to?(:hyperion_handler, true) ? method(:hyperion_handler).loosen_args : proc{}
+    end
+
+    def built_in_handler(project, render)
+      proc do |result|
+        result.when(HyperionStatus::SUCCESS, &Proc.pipe(:body, render, project))
+        result.when(HyperionStatus::BAD_ROUTE, &method(:on_bad_route))
+        result.when(HyperionStatus::CLIENT_ERROR, &method(:on_client_error))
+        result.when(HyperionStatus::SERVER_ERROR, &method(:on_server_error))
+      end
+    end
+
+    def on_bad_route(response)
+      body = ClientErrorResponse.new("Got HTTP 404 for #{response.route}. Is the route implemented?", [], ClientErrorCode::UNKNOWN)
+      report_client_error(response.route, body)
+    end
+
+    def on_client_error(response)
+      report_client_error(response.route, response.body)
+    end
+
+    def report_client_error(route, body)
+      generic_msg = "The request failed: #{route}"
+
+      if body.is_a?(ClientErrorResponse)
+        hyperion_raise body.message
+      elsif body.nil?
+        hyperion_raise generic_msg
+      else
+        hyperion_raise "#{generic_msg}: #{body}"
+      end
+    end
+
+    def on_server_error(response)
+      hyperion_raise "#{response.route}\n#{response.body}"
+    end
+
+    def fallthrough(result)
+      hyperion_raise "Hyperion error: the response did not match any conditions: #{result.to_s}"
+    end
+  end
+end

data/lib/hyperion/result_handling/dispatch_dsl.rb

@@ -0,0 +1,67 @@
+require 'hyperion/aux/util'
+require 'hyperion/types/hyperion_result'
+require 'hyperion/types/client_error_detail'
+
+class Hyperion
+  # This is a DSL of sorts that gives the `request` block a nice way
+  # to dispatch the result based on status, HTTP code, etc.
+  module DispatchDsl
+
+    def __set_escape_continuation__(k)
+      @escape = k
+    end
+
+    def when(condition, &action)
+      pred = as_predicate(condition)
+      is_match = Util.nil_if_error { Proc.loose_call(pred, [self]) }
+      if is_match
+        return_value = action.call(self)
+        @escape.call(return_value)  # non-local exit
+      else
+        nil
+      end
+    end
+
+    private
+
+    def as_predicate(condition)
+      if condition.is_a?(HyperionStatus)
+        status_checker(condition)
+
+      elsif condition.is_a?(ClientErrorCode)
+        client_error_code_checker(condition)
+
+      elsif condition.is_a?(Integer)
+        http_code_checker(condition)
+
+      elsif condition.is_a?(Range)
+        range_checker(condition)
+
+      elsif condition.callable?
+        condition
+
+      else
+        fail "Not a valid condition: #{condition.inspect}"
+      end
+    end
+
+    def status_checker(status)
+      proc { |r| r.status == status }
+    end
+
+    def client_error_code_checker(code)
+      proc do |r|
+        r.status == HyperionStatus::CLIENT_ERROR &&
+            r.body.errors.detect(:code, code)
+      end
+    end
+
+    def http_code_checker(code)
+      proc { |r| r.code == code }
+    end
+
+    def range_checker(range)
+      proc { |r| range.include?(r.code) }
+    end
+  end
+end

data/lib/hyperion/result_handling/dispatching_hyperion_result.rb

@@ -0,0 +1,10 @@
+require 'hyperion/types/hyperion_result'
+require 'hyperion/result_handling/dispatch_dsl'
+
+class Hyperion
+  # PW: distinguishing between this and HyperionResult is of
+  # dubious value. Consider merging the two.
+  class DispatchingHyperionResult < HyperionResult
+    include DispatchDsl
+  end
+end

data/lib/hyperion/result_handling/result_maker.rb

@@ -0,0 +1,64 @@
+require 'hyperion/formats'
+require 'hyperion/result_handling/dispatching_hyperion_result'
+require 'hyperion/types/hyperion_result'
+require 'hyperion/types/client_error_response'
+
+class Hyperion
+  # Produces a hyperion result object from a typhoeus result object
+  class ResultMaker
+    include Hyperion::Formats
+
+    def self.make(route, typho_result, continuation=nil)
+      self.new(route).make(typho_result, continuation)
+    end
+
+    def initialize(route)
+      @route = route
+    end
+
+    def make(typho_result, continuation=nil)
+      if continuation
+        result = make_from_typho(typho_result, DispatchingHyperionResult)
+        result.__set_escape_continuation__(continuation)
+        result
+      else
+        make_from_typho(typho_result, HyperionResult)
+      end
+    end
+
+    private
+
+    attr_reader :route
+
+    def make_from_typho(typho_result, result_class)
+      # TODO: should this use the response's 'Content-Type' instead of response_descriptor.format?
+      read_body = proc { read(typho_result.body, route.response_descriptor) }
+      code = typho_result.code
+
+      if typho_result.success?
+        result_class.new(route, HyperionStatus::SUCCESS, code, read_body.call)
+
+      elsif typho_result.timed_out?
+        result_class.new(route, HyperionStatus::TIMED_OUT)
+
+      elsif code == 0
+        result_class.new(route, HyperionStatus::NO_RESPONSE)
+
+      elsif code == 404
+        result_class.new(route, HyperionStatus::BAD_ROUTE, code)
+
+      elsif (400..499).include?(code)
+        hash_body = read(typho_result.body, :json)
+        err = ClientErrorResponse.from_attrs(hash_body) || hash_body
+        result_class.new(route, HyperionStatus::CLIENT_ERROR, code, err)
+
+      elsif (500..599).include?(code)
+        result_class.new(route, HyperionStatus::SERVER_ERROR, code, read_body.call)
+
+      else
+        result_class.new(route, HyperionStatus::CHECK_CODE, code, read_body.call)
+      end
+    end
+
+  end
+end

data/lib/hyperion/types/client_error_code.rb

@@ -0,0 +1,9 @@
+require 'abstractivator/enum'
+
+define_enum :ClientErrorCode,
+            :missing,            # the resource does not exist
+            :missing_field,      # a required field on a resource has not been set ()
+            :invalid,            # a parameter or the content of a POSTed document/field is invalid
+            :unsupported,        # an unsupported message type, message version, or format was requested
+            :already_exists,     # another resource has the same unique key
+            :unknown             # something else

data/lib/hyperion/types/client_error_detail.rb

@@ -0,0 +1,46 @@
+require 'hyperion/types/client_error_code'
+
+class ClientErrorDetail
+  attr_reader :code      # [ClientErrorCode]            type of error
+  attr_reader :resource  # [String]                     the thing with the error
+  attr_reader :field     # [String, Nil]                the location of the error within the resource
+  attr_reader :value     # [Object, Nil]                the problematic data
+  attr_reader :reason    # [Object, Nil]                an explanation of the error. usually a String.
+
+  def initialize(code, resource, opts={})
+    @code = canonical_code(code)
+    @resource = resource
+    @field = opts[:field] || ''
+    @value = opts[:value] || ''
+    @reason = opts[:reason] || ''
+  end
+
+  def as_json
+    {
+        'code' => code.value,
+        'resource' => resource,
+        'field' => field,
+        'value' => value,
+        'reason' => reason
+    }
+  end
+
+  def self.from_attrs(attrs)
+    code = ClientErrorCode.from(attrs['code'])
+    resource = attrs['resource']
+    field = attrs['field']
+    value = attrs['value']
+    reason = attrs['reason']
+    self.new(code, resource, field: field, value: value, reason: reason)
+  end
+
+  # make mongoid validations happy
+  def to_s; reason; end
+  def empty?; false; end
+
+  private
+
+  def canonical_code(x)
+    x.is_a?(Symbol) ? ClientErrorCode.from_symbol(x) : ClientErrorCode.from(x)
+  end
+end

data/lib/hyperion/types/client_error_response.rb

@@ -0,0 +1,50 @@
+require 'hyperion/aux/util'
+require 'hyperion/types/client_error_code'
+require 'hyperion/types/client_error_detail'
+
+class ClientErrorResponse
+  # The structure expected in a 400 response.
+
+  attr_reader :code     # [ClientErrorCode]  The type of error. At least one of the ErrorInfos should have the same code.
+  attr_reader :message  # [String]                     An error message that can be presented to the user
+  attr_reader :errors   # [Array<ErrorInfo>]           Structured information with error specifics
+  attr_reader :content  # [String, nil]                Optional content to return; may be an application-specific description of the error.
+
+  def initialize(message, errors, code=nil, content=nil)
+    Hyperion::Util.guard_param(message, 'a message string', String)
+    Hyperion::Util.guard_param(errors, 'an array of errors', &method(:error_array?))
+    code = ClientErrorCode.from(code || errors.first.try(:code) || ClientErrorCode::UNKNOWN)
+    Hyperion::Util.guard_param(code, 'a code') { ClientErrorCode.values.include?(code) }
+
+    @message = message
+    @code = code
+    @errors = errors
+    @content = content
+  end
+
+  def as_json(*_args)
+    {
+        'message' => message,
+        'code' => code.value,
+        'errors' => errors.map(&:as_json),
+        'content' => content
+    }
+  end
+
+  def self.from_attrs(attrs)
+    Hyperion::Util.nil_if_error do
+      message = attrs['message']
+      return nil if message.blank?
+      content = attrs['content']
+      code = code || ClientErrorCode.from(attrs['code'])
+      errors = (attrs['errors'] || []).map(&ClientErrorDetail.method(:from_attrs))
+      self.new(message, errors, code, content)
+    end
+  end
+
+  private
+
+  def error_array?(xs)
+    xs.is_a?(Array) && xs.all?{|x| x.is_a?(ClientErrorDetail)}
+  end
+end

data/lib/hyperion/types/hyperion_error.rb

@@ -0,0 +1,6 @@
+class HyperionError < RuntimeError
+end
+
+def hyperion_raise(msg)
+  raise HyperionError, msg
+end

data/lib/hyperion/types/hyperion_result.rb

@@ -0,0 +1,24 @@
+require 'active_support/inflector'
+
+class HyperionResult
+  attr_reader :route, :status, :code, :body
+
+  # @param status [HyperionStatus]
+  # @param code [Integer] the HTTP response code
+  # @param body [Object, Hash<String,Object>] the deserialized response body.
+  #   The type is determined by the content-type.
+  #   JSON is deserialized to a Hash<String, Object>
+  def initialize(route, status, code=nil, body=nil)
+    @route, @status, @code, @body = route, status, code, body
+  end
+
+  def to_s
+    if status == HyperionStatus::CHECK_CODE
+      "HTTP #{code}: #{route.to_s}"
+    elsif status == HyperionStatus::BAD_ROUTE
+      "#{status.value.to_s.humanize} (#{code}): #{route.to_s}"
+    else
+      "#{status.value.to_s.humanize}: #{route.to_s}"
+    end
+  end
+end

data/lib/hyperion/types/hyperion_status.rb

@@ -0,0 +1,10 @@
+require 'abstractivator/enum'
+
+define_enum :HyperionStatus,
+            :success,
+            :timed_out,
+            :no_response,
+            :bad_route,        # 404 (route not implemented)
+            :client_error,     # 400
+            :server_error,     # 500
+            :check_code        # everything else