api-transformer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 87a3b324b1f0fd77ef0091e47311ef9e0029b92a
+  data.tar.gz: 7cf42588afe1e037df1ce743e4ac2c0e4c5a2398
+SHA512:
+  metadata.gz: ddf7f252707a1340651a815251a1597a461495cee7be30a70521c01faea1d5c1394af59c753cb34422e96a3a91d61494fd22f515ed036cd27416fa123ac622a0
+  data.tar.gz: e670c237da02b04c635ad9b7ad76acec3612b8640afe0174257903802276d56d55852c5461324885634a41a8d5866b44190a35698f532a2f0fb89f68b1da5fcb

data/.gitignore

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

data/.overcommit.yml

@@ -0,0 +1,27 @@
+# Use this file to configure the Overcommit hooks you wish to use. This will
+# extend the default configuration defined in:
+# https://github.com/causes/overcommit/blob/master/config/default.yml
+#
+# At the topmost level of this YAML file is a key representing type of hook
+# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can
+# customize each hook, such as whether to only run it on certain files (via
+# `include`), whether to only display output if it fails (via `quiet`), etc.
+#
+# For a complete list of hooks, see:
+# https://github.com/causes/overcommit/tree/master/lib/overcommit/hook
+#
+# For a complete list of options that you can use to customize hooks, see:
+# https://github.com/causes/overcommit#configuration
+#
+# Uncomment the following lines to make the configuration take effect.
+
+PreCommit:
+ Rubocop:
+   on_warn: fail # Treat all warnings as failures
+
+#PostCheckout:
+#  ALL: # Special hook name that customizes all hooks of this type
+#   quiet: true # Change all post-checkout hooks to only display output on failure
+#
+#  IndexTags:
+#    enabled: true # Generate a tags file with `ctags` each time HEAD changes

data/.rubocop.yml

@@ -0,0 +1,9 @@
+inherit_from: .rubocop_todo.yml
+
+# Rubocop defaults to single quotes, but arbitrarily so
+StringLiterals:
+  EnforcedStyle: double_quotes
+
+# api-tranformer is a DSL
+Style/TrivialAccessors:
+  AllowDSLWriters: true

data/.rubocop_todo.yml

@@ -0,0 +1,15 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2014-09-12 14:27:20 -0700 using RuboCop version 0.24.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+Style/ClassVars:
+  Enabled: false
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Max: 110

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.2
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in api-transformer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Bruz Marzolf
+
+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,358 @@
+[![Build Status](https://travis-ci.org/CXInc/api-transformer.svg)](https://travis-ci.org/CXInc/api-transformer)
+[![Code Climate](https://codeclimate.com/github/CXInc/api-transformer/badges/gpa.svg)](https://codeclimate.com/github/CXInc/api-transformer)
+
+# api-transformer
+
+**NOTE: this is currently a work in progress**
+
+A Ruby web server DSL for exposing one or more back-end services through a different API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "api-transformer"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install api-transformer
+```
+
+## Usage
+
+### Quick Start
+
+Create a file ip_server.rb:
+
+```ruby
+require 'api_transformer'
+
+class IpServer < ApiTransformer::Server
+  base_url "http://ip.jsontest.com/"
+
+  get "/ip" do
+    request :ip do
+      path "/"
+      method :get
+    end
+
+    response do |data|
+      success do
+        status 200
+        attribute :your_ip, data[:ip][:ip]
+      end
+    end
+  end
+end
+```
+
+Run it:
+
+```bash
+$ ruby ip_server.rb -sv
+```
+
+Try it:
+
+```bash
+$ curl -i http://localhost:9000/ip
+HTTP/1.1 200 OK
+Server: Goliath
+Date: Tue, 30 Sep 2014 23:19:34 GMT
+
+{"your_ip":"74.125.228.96"}
+```
+
+Let's break this down:
+
+```ruby
+base_url "http://ip.jsontest.com/"
+```
+
+Declare the base URL for back-end requests, which will each provide a path under this.
+
+```ruby
+get "/ip" do |params|
+```
+
+This defines a single endpoint that responds to GET requests at the path '/ip'.
+
+    request :ip do
+      path "/"
+      method :get
+    end
+
+It makes a single GET request to the root path of the base_url (http://ip.jsontest.com/).
+
+```ruby
+response do |data|
+  success do
+    status 200
+    attribute :your_ip, data[:ip][:ip]
+  end
+end
+```
+
+Upon completion of the request to ip.jsontest.com with a 2XX response, it responds with a status of 200 and a JSON attribute of your_ip.
+
+### Endpoints without any requests
+
+Back-end requests are not required.
+
+```ruby
+get "/ping" do
+  response do
+    success { attribute :result, "pong" }
+  end
+end
+```
+
+### Accepting parameters
+
+Query params:
+
+```ruby
+get "/some_params" do
+  request :greeting do
+    path "/greeting"
+    method :get
+
+    query_param :greeting, "hello"
+    query_param :name, "Bob"
+  end
+
+  response do
+    success { attribute :result, "hello Bob" }
+  end
+end
+```
+
+Form params:
+
+```ruby
+post "/some_params" do
+  request :greeting do
+    path "/greeting"
+    method :post
+
+    form_param :greeting, "hello"
+    form_param :name, "Bob"
+  end
+
+  response do
+    success { attribute :result, "hello Bob" }
+  end
+end
+```
+
+JSON params:
+
+```ruby
+post "/some_params" do
+  request :greeting do
+    path "/greeting"
+    method :post
+
+    json_param :greeting, "hello"
+    json_param :name, "Bob"
+  end
+
+  response do
+    success { attribute :result, "hello Bob" }
+  end
+end
+```
+
+JSON params are accepted as a JSON-encoded request body. In this case what would get sent to the back-end endpoint is {"greeting":"hello","name":"Bob"}.
+
+Form and JSON params can't both be used on the same request.
+
+### HTTP verbs
+
+GET, POST, PUT and DELETE are provided:
+
+```ruby
+delete "/ping" do
+  response do
+    success { attribute :result, "I should probably delete something" }
+  end
+end
+```
+
+### Pass-through of headers
+
+```ruby
+get "/user_agent" do |_, headers|
+  response do
+    success { attribute :user_agent, headers["User-Agent"] }
+  end
+end
+```
+
+### JSON objects and arrays
+
+Classes can be used to parse data and return JSON objects:
+
+```ruby
+class Bob
+  def initialize(last_name)
+    @last_name = last_name
+  end
+
+  def to_hash
+    { first_name: "Bob", last_name: @last_name }
+  end
+end
+
+get "/object" do
+  response do
+    success { object :bob, Bob, "Saget" }
+  end
+end
+
+# => {"bob":{"first_name":"Bob","last_name":"Saget"}}
+```
+
+These can also be used to return arrays of data:
+
+```ruby
+get "/array" do
+  response do
+    success { array :bobs, Bob, %w(Ross Marley) }
+  end
+end
+
+# => {"bobs":[{"first_name":"Bob","last_name":"Ross"},{"first_name":"Bob","last_name":"Marley"}]}
+```
+
+### Use request data on subsequent requests
+
+This is perhaps easiest to explain with an example:
+
+```ruby
+get "/multi" do
+  request :one do
+    path "/one"
+    method :get
+  end
+
+  request :two do |data|
+    path "/two"
+    method :get
+
+    query_param :name, data[:one][:name]
+  end
+
+  response do |data|
+    success { attribute :name, data[:two][:result] }
+  end
+end
+
+get "/one" do
+  response do
+    success { attribute :name, "Bob" }
+  end
+end
+
+get "/two" do |params|
+  response do
+    success { attribute :result, params[:name] }
+  end
+end
+```
+
+Notably, on this line:
+
+```ruby
+request :two do |data|
+```
+
+`data` will contain the response data from the first request.
+
+### Conditional requests
+
+It can be useful to only send back-end requests under certain conditions:
+
+```ruby
+get "/conditional" do |params|
+  request :start_background_job, when: params[:make_it_so] do
+    path "/job"
+    method :post
+  end
+
+  response do
+    success { attribute :result, "OK" }
+  end
+end
+```
+
+### Streaming
+
+It can be done without a back-end request:
+
+```ruby
+get "/stream_no_backend" do
+  stream true
+
+  response do
+    success do
+      stream do
+        (1..9).each { |n| stream_write n }
+      end
+    end
+  end
+end
+```
+
+Things to notice:
+ - Inside the endpoint block, `stream true` is needed
+ - Inside the success block, there's a `stream` block
+ - The `stream` block uses `stream_write` to write the response
+
+This gets more useful when proxying to a back-end request that is going to return a lot of data:
+
+```ruby
+get "/stream_download" do
+  stream true
+
+  request :download do
+    path "/huge_download"
+    method :get
+  end
+
+  response do |data|
+    success do
+      stream do
+        data[:one].stream do |chunk|
+          stream_write chunk
+        end
+      end
+    end
+  end
+end
+```
+
+The `stream do |chunk|` block will receive the data in small chunks as it comes off the socket, so that the entire response body doesn't go into memory.
+
+## Testing
+
+```bash
+$ rake
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/CXInc/api-transformer/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am "Add some feature"`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+task default: [:test]
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end

data/api-transformer.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "api_transformer/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "api-transformer"
+  spec.version       = ApiTransformer::VERSION
+  spec.authors       = ["Bruz Marzolf"]
+  spec.email         = ["bruz@bruzilla.com"]
+  spec.summary       = "API transformation Ruby DSL and server"
+  spec.description   = ""
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rack", "~> 1.5"
+  spec.add_dependency "goliath", "~> 1.0"
+  spec.add_dependency "em-http-request", "~> 1.1"
+  spec.add_dependency "json", "~> 1.8"
+  spec.add_dependency "hashie", "~> 3.3"
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "pry", "~> 0.10"
+  spec.add_development_dependency "mocha", "~> 1.1"
+end

data/examples/ip_server.rb

@@ -0,0 +1,19 @@
+require_relative '../lib/api_transformer'
+
+class IpServer < ApiTransformer::Server
+  base_url "http://ip.jsontest.com"
+
+  get "/ip" do
+    request :ip do
+      path "/"
+      method :get
+    end
+
+    response do |data|
+      success do
+        status 200
+        attribute :your_ip, data[:ip][:ip]
+      end
+    end
+  end
+end

data/lib/api/transformer.rb

@@ -0,0 +1 @@
+require_relative "../api_transformer"

data/lib/api_transformer/backend_request.rb

@@ -0,0 +1,79 @@
+require "em-synchrony/em-http"
+
+module ApiTransformer
+  # Process request blocks
+  class BackendRequest
+    attr_reader :name
+    attr_accessor :path, :method, :query_params, :form_params, :json_params,
+                  :cookie_params
+
+    def initialize(name, base_url, frontend_headers)
+      @name = name
+      @base_url = base_url
+      @frontend_headers = frontend_headers
+
+      @query_params = {}
+      @form_params = {}
+      @json_params = {}
+      @cookie_params = {}
+    end
+
+    def send
+      url = @base_url + @path
+
+      EM::HttpRequest.new(url).send(
+        "a#{@method}",
+        query: @query_params,
+        body: body,
+        head: headers
+      )
+    end
+
+    private
+
+    def body
+      case [@form_params.any?, @json_params.any?]
+      when [true, true]
+        fail RequestError, "A request cannot have both json and form parameters"
+      when [true, false]
+        @form_params
+      when [false, true]
+        @json_params.to_json
+      when [false, false]
+        nil
+      end
+    end
+
+    def headers
+      ret = [stripped_frontend_headers, content_type, cookies].reduce(&:merge)
+      ret.delete("Host")
+      ret
+    end
+
+    def stripped_frontend_headers
+      @frontend_headers.reject { |key, _| key == "Content-Length" }
+    end
+
+    def content_type
+      if @json_params.any?
+        { "Content-Type" => "application/json" }
+      elsif @form_params.any?
+        { "Content-Type" => "application/x-www-form-urlencoded" }
+      else
+        {}
+      end
+    end
+
+    def cookies
+      if @cookie_params.any?
+        cookie_string = @cookie_params
+          .map { |key, value| "#{key}=#{value};" }
+          .join(" ")
+
+        { "Cookie" => cookie_string }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/api_transformer/backend_request_sender.rb

@@ -0,0 +1,56 @@
+module ApiTransformer
+  # Processes the request block
+  class BackendRequestSender
+    def initialize(name, options, block, frontend_headers, helper_blocks)
+      @backend_request = BackendRequest.new(
+        name,
+        options[:base_url],
+        frontend_headers
+      )
+
+      @block = block
+      @helper_blocks = helper_blocks
+    end
+
+    def send(backend_responses)
+      @helper_blocks.each { |block| instance_eval(&block) }
+      instance_exec(backend_responses, &@block)
+
+      unless @backend_request.method
+        fail RequestError, "Missing method for backend request: #{request_name}"
+      end
+
+      @backend_request.send
+    end
+
+    def request_name
+      @backend_request.name
+    end
+
+    private
+
+    def path(value)
+      @backend_request.path = value
+    end
+
+    def method(value)
+      @backend_request.method = value
+    end
+
+    def query_param(key, value)
+      @backend_request.query_params[key] = value
+    end
+
+    def form_param(key, value)
+      @backend_request.form_params[key] = value
+    end
+
+    def json_param(key, value)
+      @backend_request.json_params[key] = value
+    end
+
+    def cookie_param(key, value)
+      @backend_request.cookie_params[key] = value
+    end
+  end
+end