hyperion_http 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fe93d63e5710f95bd417f7281c7c3b96c267e625
+  data.tar.gz: 13daa226ae477357aacb51fa413f85f9967fed25
+SHA512:
+  metadata.gz: 453822633702779a4fd790ef9527643865b42c8efb6ec3292dffa7cdb5e86457737062d106dfc978b3360c11aad670353f54f42b823858e9e26f4a6fbe0e760c
+  data.tar.gz: c5c618b3a65d8090964c9f0d36aafb050c2f75c8758a8100c2e873bd9e619b54a37db34e35a31b962ce20e9f9597fb6304ad3944cdb4d6dda15af69aabc31188

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea
+\#*\#
+.\#*
+*.gem

data/.rspec

@@ -0,0 +1,4 @@
+--format progress
+-I spec/lib
+--require 'support/core_helpers.rb'
+--color

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0.0-p247
+branches:
+  only:
+    - master
+    - /^[ftb]-.*$/

data/CHANGES.md

@@ -0,0 +1,145 @@
+### 0.0.16
+- Hyperion::request can now take a block an easily dispatch on response status, code, or other stuff
+
+### 0.0.17
+- If Hyperion.fake allow is passed a route, its block can now return an object instead of a rack-style response.
+  The object is serialized according to the route's response descriptor.
+- Serialize the POST/PUT payload according to the route's payload descriptor.
+
+### 0.0.18
+- Return 404 instead of crashing when headers are the only thing preventing a faked route from matching.
+
+### 0.0.19
+- Log stubs and requests for debugging purposes.
+
+### 0.0.20
+- Added contracts to some public methods to provide more helpful error messages when passed invalid arguments.
+
+### 0.0.25
+- Allow payload descriptor to be nil (for things like DELETE).
+
+### 0.0.26
+- Fixed bug with Hyperion fake not defaulting the port to 80
+
+### 0.0.27
+- Use Rails.logger if present
+
+### 0.0.28
+- Use Rails.logger if present and not nil
+
+### 0.0.29
+- Pretty RestRoute.to_s
+- Added the ability to match responses on an HTTP code range
+
+### 0.0.30
+- locked 'contracts' gem to version 0.5 due to possible incompatibility with ascent-web
+
+### 0.0.31
+- disabled method contracts due to apparent weirdness
+- enable Oj's 'compat' mode to allow writing of both string- and symbol-keyed hashes
+- write Time objects to JSON as ISO 8601 (Indigo convention)
+
+### 0.0.32
+- Include requested route on response object
+
+### 0.0.33
+- Pretty HyperionResult#to_s
+
+### 0.0.34
+- HyperionUri (models query params as a hash)
+- Fixed logging bug where the logger would capture $stdout the first time it saw it
+  and always use that object instead of always using the current value of $stdout.
+
+### 0.0.35
+- Canonicalize HyperionUri#to_s output by sorting query param names to make route matching possible.
+
+### 0.0.36
+- Pretty ResponseDescriptor#to_s
+- When using Hyperion.fake and a rack result is returned, the body is serialized as JSON
+  if it is not already a string.
+- If parsing JSON fails, just return the unparsed JSON. (For 400s).
+
+### 0.0.37
+- Pass the HyperionResult to the `when` block, since it won't always be in lexical scope.
+
+### 0.0.38
+- Added superion
+- Catch raised errors in handler predicates
+- Read 400-level bodies as ClientErrorResponse
+
+### 0.0.39
+- Refactored to appease CodeClimate
+
+### 0.0.40
+- Moved mimic back to being a runtime dependency
+
+### 0.0.41
+- Fixed ClientErrorResponse#from_attrs
+
+### 0.0.42
+- Made ClientErrorResponse constructor interface less error-prone
+- Always read client error response as JSON
+
+### 0.0.43
+- Raise an error if superion response falls through and no superion_fallthrough method is defined.
+
+### 0.0.44
+- Fixed "require" problems
+
+### 0.0.45
+- Support query params that are arrays
+
+### 0.0.46
+- Allow query to be nil (bugfix)
+
+### 0.0.47
+- Fixed slow POSTs > 1KB
+
+### 0.0.48
+- Fixed bug where superion's interface was too loose
+- Do not require dispatch predicates to take an argument
+- Log when requests complete
+
+### 0.0.50
+- Allow dispatching on client error code
+
+### 0.0.52
+- `ErrorInfo` -> `ClientErrorDetail`
+- `ErrorInfo::Code` -> `ClientErrorCode`
+- `HyperionResult::Status` -> `HyperionStatus`
+- `ClientErrorResponse.new` signature changed
+- superion was absorbed into hyperion. instead, `require 'hyperion'`
+  and `include Hyperion::Requestor`
+- `superion_handler` -> `hyperion_handler`
+- removed `superion_fallthrough`. it's only hit on 100s and 300s.
+  Custom handlers can already handle those if they want. An error is
+  raised if a 100 or 300 falls through.
+- removed `Superion.missing`
+
+### 0.0.53
+- Fixed bug due to missing `require`
+
+### 0.0.54
+- abstractivator 0.0.27
+
+### 0.0.55
+- upgraded abstractivator for wrapped enum values
+
+### 0.0.56
+- another enum tweak
+
+### 0.0.57
+- json enum support from abstractivator
+
+### 0.0.58
+- Renamed `ClientErrorResponse#body` -> `ClientErrorResponse#content`
+
+### 0.1.0
+- Bumped version
+
+### 0.1.1
+- Attempted to solve problem in tests where clients hit an old server while
+  it's shutting down, resulting in a timeout.
+
+### 0.1.2
+- Fixed broken gemspec version for abstractivator

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hyperion.gemspec
+gemspec
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Peter Winton
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,421 @@
+# Hyperion
+[![Build Status](https://travis-ci.org/indigo-biosystems/hyperion.svg)](https://travis-ci.org/indigo-biosystems/hyperion) 
+
+Hyperion is a Ruby REST client that follows certain conventions
+layered on top of HTTP. The conventions implement best practices
+surrounding versioning, error reporting, and crafting an API for
+consumption by third parties. Hyperion provides abstractions that
+make it easy to follow these conventions consistently across
+projects.
+
+This document describes the conventions, then demonstrates how to
+use the API, and finally shows how to test your client-side code.
+
+## Conventions
+
+The conventions are modeled after [GitHub's Developer API](https://developer.github.com/v3/).
+
+### Versioning
+
+According to best practices, hyperion uses both _resource_ versioning and
+_message_ versioning.
+
+#### Message versioning
+
+A client sends a _request_ to the server, and the server returns a
+_response_. The request and response each have a message type with a
+well specified structure. When placing the request, the client
+specifies the type of messages it expects back. For PUT, POST, and
+PATCH requests, the client also specifies the message type of the
+payload it is sending with the request.
+
+A client might send a request with the header:
+
+`Accept: application/vnd.indigobio-ascent.user-v1+json`
+
+which indicates that the server must return an "ascent.user" message, version
+1, formatted as JSON. If the server does not support this, it must
+return a 400-level error (discussed below).
+
+A client POSTing a new user also includes the header:
+
+`Content-Type: application/json`
+
+indicating that it is sending JSON. The server takes the Accept header
+message type to be the type of the request payload.
+<!--- ^ seems fishy -->
+
+The message version is incremented when the message structure changes.
+
+_Note: Message types are currently established via documentation. In
+the future, it would be desirable for them to be declared precisely in
+a [protobuf](https://github.com/google/protobuf)-like form, which would
+allow for generated documentation, simpler serialization code,
+automatic validation, and enhanced logging and diagnostics._
+
+#### Resource versioning
+
+Less frequently, the semantics of a given resource change. There are
+several ways a server can route a particular resource version,
+including:
+
+- `/v2/` - incorporating the version in the URI
+- `?v=2` - accepting the version as a query parameter
+- `v2.archiver.indigobio.com` - incorporating the version in the hostname
+- creating a differently named resource altogether
+
+Hyperion does not expressly support any of these conventions, although
+it may in the future.
+
+
+### Client Errors
+
+The server always returns 400-level errors as exactly 400; no
+distinction is made in the HTTP response code. Instead, the server
+returns a well-defined "client error response" structure that contains
+
+- a human-oriented error message, and
+- a machine-oriented list of "error detail" structures.
+
+The _message_ describes the problem. The _error details_ provide
+enough information to begin resolving the problem.
+
+An error detail consists of:
+
+- code (not to be confused with the HTTP status code, _e.g._, 200)
+- reason
+- resource
+- field
+- value
+
+The _code_ is an enumeration value (_e.g._, "missing", "invalid",
+"unsupported") which describes the type of problem with the request.
+<!--- ^ consider renaming "code" to "problem" -->
+
+The _reason_ explains why the problem occurred.
+
+The problem is associated with a particular _resource_, and perhaps
+more specifically with a particular _field_ and _value_ on that resource.
+
+Each field is a string. Depending on the code, some fields may not
+apply. Inapplicable fields are always present, with the empty string
+as their value. This simplifies the code that deals with them.
+
+
+### Server Errors
+
+Server errors are returned as normal 500 responses, which may or may
+not have a body. There is no special treatment.
+
+
+## Using hyperion
+
+Hyperion's API revolves around the idea of a _route_, which is a
+combination of:
+
+- HTTP method
+- URI
+- parameters that influence header generation and de/serialization
+  - `ResponseDescriptor` (what kind of data do we want back)
+    - influences the `Accept` header
+  - `PayloadDescriptor` (what kind of data is being PUT or POSTed)
+    - influences the `Content-Type` header
+
+Hyperion automatically deserializes responses according to the
+`ResponseDescriptor` and serializes the request payload according to
+the `PayloadDescriptor`.
+
+Hyperion provides a basic interface for requesting routes.
+
+```ruby
+require 'hyperion'
+
+message_type = 'user'
+version = 1
+format = :json
+route = RestRoute.new(:get, 'http://somesite.org/users/0', ResponseDescriptor.new(message_type, version, format))
+user = Hyperion.request(route)
+```
+
+You can pass `request` a block, in which case the return value of the
+block becomes the return value of `request`.
+
+```ruby
+user = Hyperion.request(route) do |result|
+  if result.status == HyperionResult::Status::SUCCESS
+    User.new(result.body)
+  end
+end
+```
+
+Production-quality error handling becomes hairy quickly, so hyperion
+provides a mini DSL to make it easier.
+
+```ruby
+Hyperion.request(route) do |result|
+  result.when(HyperionResult::Status::SUCCESS) { User.new(result.body) }
+  result.when(400..499) { raise 'we screwed up' }
+  result.when(500..599) { raise 'they screwed up' }
+  result.when(evil) { exit(1) }
+end
+
+def evil
+  proc do |result|
+    result.body['things'].any?{|x| x['id'] == '666'}
+  end
+end
+```
+
+Conditions are tested in order. When hyperion encounters the first
+true condition, it executes the associated block, the value of which
+becomes the return value of `request`.
+
+A condition may be:
+
+- a `HyperionResult::Status` enumeration member,
+- an `ErrorInfo::Code` enumeration member,
+- an HTTP code,
+- a range of HTTP codes, or
+- an arbitrary [predicate](http://en.wikipedia.org/wiki/Predicate_(mathematical_logic)).
+
+To obviate guard logic in predicates, a predicate that raises an
+exception is treated as a non-match. In the example above, if the body
+didn't have a `'things'` key, then `.any?` would raise a
+`NoMethodError`, interpreted as a non-match, and hyperion would move
+on to the next predicate.
+
+### Route classes
+
+In practice, you don't want to litter your code with `RestRoute.new`
+invocations. Here is a pattern for encapsulating the routes. It is the
+client-side analog of `routes.rb` in Rails.
+
+```ruby
+class CrudRoutes
+  def initialize(resource)
+    @resource = resource
+  end
+
+  def read(id)
+    build(:get, id, response(message_type_for(@resource), 1, :json))
+  end
+
+  def create
+    build(:post, '', response(message_type_for(@resource), 1, :json), payload(:json))
+  end
+
+  ...
+end
+```
+
+You can easily imagine the rest of the routes and what the helper
+methods `build`, `message_type_for`, `response`, and `payload` look like.
+
+Use it like this:
+
+```ruby
+user_routes = CrudRoutes.new('users')
+Hyperion.request(user_routes.create, body: {name: 'joe', email: 'joe@schmoe.com'})
+# later...
+joe = Hyperion.request(user_routes.read(joes_id))
+```
+
+A few notes:
+
+`CrudRoutes` functions as an API spec, albeit a stripped down one.
+Therefore, there is no need to write specs for it; the specs would
+likely be harder to understand than the code itself. `CrudRoutes`
+could be DRYed up more, but that would reduce its understandability
+and create the need for specs.
+
+See `AssaymaticRoutes` in ascent-web for the most complete example to
+date.
+
+
+### Configuration
+
+```ruby
+# configure hyperion
+Hyperion.configure do |config|
+  config.vendor_string = 'indigobio-ascent'  # becomes part of the Accept header
+end
+```
+
+
+## Superion
+
+Superion layers more convenience onto Hyperion by helping dispatch the
+response: internalizing the response and dealing with errors.
+
+### Render and project
+
+```ruby
+require 'superion'
+
+class UserGateway
+  include Superion
+
+  def find(id)
+    route = RestRoute.new(:get, "http://somesite.org/users/#{id}")
+    user = request(route, render: as_user)
+  end
+
+  def as_user
+    proc do |hash|
+      User.new(hash)
+    end
+  end
+end
+```
+
+On success, the "render" proc has a chance to transform the body
+(usually a `Hash`) into an internal representation (often an entity).
+
+After rendering, a "project" proc (the block) has a chance to project
+the rendered entity; for example, by choosing a subdocument or field.
+
+```ruby
+def user_names
+  route = RestRoute.new(:get, "http://somesite.org/users")
+  request(route, render: as_users) do |users|
+    users.map(&:name)
+  end
+end
+```
+
+### Result dispatch
+
+Superion has four levels of dispatching:
+
+- _core_,
+- _includer_, and
+- _request_.
+
+<!--- TODO: these terms could use improvement. -->
+
+They are distinguished by their scope. The core handler is built into
+superion. An includer handler affects all requests made by a
+particular class. A request handler affects only a particular request.
+
+When superion receives a response, it passes the result through the
+request, includer, and core handlers, in that order. The first handler
+to match wins, and no further handlers are tried. If no handler
+matches, then superion raises a `HyperionError` error.
+
+#### Core
+
+The core handler handles the 200 success case and 400- and 500-level
+errors. In the success case, the body is rendered and projected. In
+the error cases, a `HyperionError` is raised. The message for 400s is
+taken from the error response. The message for 500s contains the raw
+string body. Specifically for 404, no body is available, so an error
+indicating an unimplemented route is raised.
+
+
+#### Includer
+
+The includer handler is an optional method on the requesting class.
+
+```ruby
+class UserGateway
+  include Superion
+
+  def find(id)
+    ...
+  end
+
+  def superion_handler(result)
+    result.when(ErrorInfo::MISSING) { raise "The resource was not found: #{result.route}" }
+    result.when(HyperionResult::Status::SERVER_ERROR) { ... }
+  end
+end
+```
+
+#### Request
+
+The request handler provides a convenient way to specify a handler as
+a `Hash` for an individual `request` call. If a `superion_handler`
+looks like:
+
+```ruby
+result.when(condition) { return_something }
+```
+
+then the equivalent request handler is
+
+```ruby
+{ condition => proc { return_something } }
+```
+
+Pass it as the `also_handle` option:
+
+```ruby
+  request(route, render: as_user, also_handle: { condition => proc { return_something } })
+```
+
+## Testing
+
+Hyperion includes methods to help test your client-side code.
+
+```ruby
+require 'hyperion_test'
+
+list_route = RestRoute.new(:get, "http://somesite.org/users")
+find_route = RestRoute.new(:get, "http://somesite.org/users/123")
+
+# start a fake server
+Hyperion.fake('http://somesite.org') do |svr|
+  svr.allow(list_route) { [User.new('123'), User.new('456')].as_json }
+  svr.allow(find_route) do |result|
+    User.new(result.body['id']).as_json
+  end
+end
+
+# then place requests against it
+users = Hyperion.request(list_route)
+expect(users[0]['id']).to eql 123
+expect(users[1]['id']).to eql 456
+```
+
+`Hyperion::fake` starts a real web server which responds to the
+configured routes. It provides an easy way to exercise the entire
+stack when running your tests.
+
+For simpler cases:
+
+```ruby
+list_route = RestRoute.new(:get, "http://somesite.org/users")
+response = [User.new('123'), User.new('456')]
+fake_route(list_route, response)
+```
+
+See the specs for details.
+
+## Maintenance
+
+When improving hyperion, increment the version in `version.rb` (Hyperion
+uses [semantic versioning](http://semver.org)) and describe your
+changes in `CHANGES.md`.
+
+## Design decisions
+
+Hyperion is backed by Typhoeus, which in turn is backed by libcurl.
+Both are fully featured, have widespread adoption, and are actively
+maintained. One particularly nice feature of Typhoeus is that it
+provides an easy way to issue multiple requests in parallel, which
+is important when you have a microservices architecture.
+
+Our original plan was to have a second gem containing `Hyperion.fake`
+and its dependencies. The problem is that you need to keep the two
+gems in sync, which reduces agility. As a compromise, `Hyperion.fake`
+still lives in the hyperion gem but is only loaded when you `require
+'hyperion_test'`. Assuming no production code `require`s
+`hyperion_test`, none of the test-related dependencies will be loaded
+in a production system, although the gem dependencies will be part of
+the production bundle.
+
+# Parking Lot
+
+- Consider making the set of supported formats/content-types extensible.
+- Consider adding a configuration value to set the logger to use. If none
+  is provided, fall back on Rails.logger, and then a new `Logger`.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :default => :spec
+rescue LoadError
+  # no rspec available
+end

data/hyperion_http.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hyperion/aux/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'hyperion_http'
+  spec.version       = Hyperion::VERSION
+  spec.authors       = ['Indigo BioAutomation, Inc.']
+  spec.email         = ['pwinton@indigobio.com']
+  spec.summary       = 'Ruby REST client'
+  spec.description   = 'Ruby REST client for internal service architecture'
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'json_spec'
+  spec.add_development_dependency 'rspec_junit_formatter'
+
+  spec.add_runtime_dependency 'abstractivator', '~> 0.0'
+  spec.add_runtime_dependency 'activesupport'
+  spec.add_runtime_dependency 'immutable_struct', '~> 1.1'
+  spec.add_runtime_dependency 'oj', '~> 2.12'
+  spec.add_runtime_dependency 'typhoeus', '~> 0.7'
+  spec.add_runtime_dependency 'mimic', '~> 0.4.3'
+end

data/lib/hyperion/aux/bug_error.rb

@@ -0,0 +1,2 @@
+class BugError < Exception
+end

data/lib/hyperion/aux/hash_ext.rb

@@ -0,0 +1,5 @@
+class Hash
+  def subhash?(hash)
+    each_pair.all?{|k, v| hash[k] == v}
+  end
+end