rack-translating_proxy 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 794652ff10fbf63964576fba30599ee1d5c34f67
-  data.tar.gz: fae17b5582bba5f993ad85bcd29d5212b45d5fde
+  metadata.gz: a259b5d2146451b5435d013f63a516cd7d10a00a
+  data.tar.gz: 8275b196335016b6c3957dab8d56eb5ba6f67709
 SHA512:
-  metadata.gz: 2d9db4752f01be1054c5f95d0e42e1f4b99fa999dc271e7887121f9de0f58562a6a08f3c91d69231475d6386ac20f016ad248a0a6e042b4999dfbdd000eaa78c
-  data.tar.gz: 3629f9946d3e9739322fa13a04d9b61f5fa46fa1dc52a12fb651d6f9ddb079b1e5b6f7bda318d9741fff016af0644028494ef341a7c67fa2672c64c86b736e8d
+  metadata.gz: 15f03547a3ad6ec121f9fc60bf797934ca8d908cb708e0fe7e4af183e72c521e0ea1f14d3aa2387246be8c45523e795671366a552bd8f5bcdc8666884fa67706
+  data.tar.gz: 09a7fc463e2ebc2ccaf839b665a83cc466613e8d9e9bae647cc2d9030bba95c8e27d6309f93aed25b0948fa1af1a4c26c1a4f3f9c0214885e6423d6785645f67

data/.rubocop.yml

@@ -0,0 +1,5 @@
+Documentation:
+  Enabled: false
+
+Style/AlignHash:
+  EnforcedColonStyle: table

data/.travis.yml

@@ -0,0 +1,15 @@
+rvm:
+  - 2.0.0
+  - 2.1
+  - ruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+
+before_script:
+  - "./spec/script/example_target_host fast &"
+  - "./spec/script/example_translating_proxy fast &"
+  - "sleep 5"
+
+bundler_args: --without local_development

data/Gemfile

@@ -4,3 +4,10 @@ gemspec
 
 gem 'rspec'
 gem 'rspec-its'
+gem 'sinatra'
+gem 'faraday'
+
+group :local_development do
+  gem 'pry'
+  gem 'shotgun'
+end

data/README.md

@@ -1,11 +1,95 @@
 # Rack::TranslatingProxy
+[![Build Status](https://travis-ci.org/promptworks/rack-translating_proxy.png?branch=master)](https://travis-ci.org/promptworks/rack-translating_proxy.png)
+[![Gem Version](https://badge.fury.io/rb/rack-translating_proxy.svg)](http://badge.fury.io/rb/rack-translating_proxy)
+[![Code Climate](https://codeclimate.com/github/promptworks/rack-translating_proxy/badges/gpa.svg)](https://codeclimate.com/github/promptworks/rack-translating_proxy)
+[![Dependency Status](https://gemnasium.com/promptworks/rack-translating_proxy.svg)](https://gemnasium.com/promptworks/rack-translating_proxy)
 
-A Proxy that `gsub`s the contents of the requests and responses in order to make a mostly transparent proxy.
-Its purpose is to aid in development and testing of integration with external services, especially when the browser has to interact with those services directly.
+An HTTP proxy that `gsub`s the contents of the requests and responses in order to make a mostly transparent proxy.
+
+It aids in the development and testing of integration with external services, especially when the browser has to interact with those services directly.
+Often, these services will only redirect to certain, predefined URLs, but your test suite spins up its services dynamically.
+This includes services like OAuth/OpenId and payment gateways (e.g. Stripe, Cybersource).
 
 ## Usage
 
-TODO: Write usage instructions here
+Inherit from `Rack::TranslatingProxy` and implement `#target_host` and `#request_mapping` hook methods to customize your translating proxy Rack app.
+
+``` ruby
+class MyTranslatingProxy < Rack::TranslatingProxy
+  def target_host
+    # ...
+  end
+
+  def request_mapping
+    # ...
+  end
+end
+```
+
+### Target host
+
+``` ruby
+def target_host
+  'https://example.com'
+end
+```
+
+Implement this method to specify which host the proxy will send all the requests to.
+If the app is running on `http://localhost:5555`, then if you call `http://localhost:5555/some/path` you will actually receive the contents of `https:///example.com/some/path`
+
+The scheme (`http://` vs `http://`) does not need to match between the proxy and target host.
+
+There is no need to memoize this method.
+
+### Request mapping
+
+``` ruby
+def request_mapping
+  {
+    'some string'       => 'another string',
+    'some other string' => 'another another string'
+  }
+end
+```
+
+Implement this method to specify which strings will be translated and to what. On requests, the keys will be translated to the values, and in the responses, the values will be translated into the keys.
+In this example, in the request, any instance or `some string` will be translated to `another string` before the proxy makes the request to the target host. When the target host responds, the proxy will translate any instance of `another string` into `some string`.
+
+On the request, the proxy will `gsub` the path, the query string, the `location` header(s) and the request body. On the response, the proxy will `gsub` the response body.
+
+You will often want to include a rule for the target host to rewrite the proxy's current URL to the target host's URL.
+This is useful particularly for handling redirects.
+For example, if you have a mapping rule like `'http://localost:5555' => 'https://externalservice.com'`, when a service redirects to `https://externalservice.com/payment-accepted`, the proxy will rewrite that to `http://localhost:555/payment-accepted`.
+
+There is no need to memoize this method.
+
+
+### Example: OAuth service
+
+Here is an example of a translating proxy for an OAuth service.
+
+``` ruby
+class OAuthProxy < Rack::TranslatingProxy
+  # the host to proxy
+  def target_host
+    'https://externalservice.com'
+  end
+
+  def request_mapping
+    {
+      # the URI of this proxy => URI of the target
+      'http://localhost:5555' => target_host,
+
+      # our dev app server    => URI that the OAuth implementation has on
+      #                          file and wants to redirect to
+      'http://localhost:3000' => 'https://dev.mydomain.com',
+    }
+  end
+end
+```
+
+Assuming you run the proxy on `localhost:5555`, you can configure your OAuth-enabled app to point to `http://localhost:5555`.
+Your test suite and your browser can hit the real OAuth server.
 
 ## Installation
 
@@ -21,9 +105,25 @@ Or install it yourself as:
 
     $ gem install rack-translating_proxy
 
+## Development
+
+Make sure you are running the test servers:
+
+    ./spec/script/example_target_host
+    ./spec/script/example_translating_proxy
+
+Then, run
+
+    rake
+
+The test servers will update automatically because they are using [shotgun](https://github.com/rtomayko/shotgun).
+If you don't need them to reload on every request, run one or both of them with the `fast` parameter, like
+
+    ./spec/script/example_target_host fast
+
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/rack-translating_proxy/fork )
+1. Fork it ( http://github.com/promptworks/rack-translating_proxy/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`)

data/Rakefile

@@ -1 +1,8 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+task default: [:spec, :rubocop]
+
+RSpec::Core::RakeTask.new
+RuboCop::RakeTask.new

data/lib/rack/translating_proxy.rb

@@ -3,10 +3,10 @@ require 'rack/proxy'
 module Rack
   class TranslatingProxy < Rack::Proxy
     def rewrite_env(env)
-      rewrite_request_url          env
-      rewrite_request_body         env
+      rewrite_request_url env
+      rewrite_request_body env
       rewrite_request_query_string env
-      rewrite_request_path         env
+      rewrite_request_path env
 
       env
     end
@@ -25,7 +25,9 @@ module Rack
     end
 
     def rewrite_request_string(str)
-      rewrite_string(str, request_mapping, URI.method(:encode_www_form_component))
+      rewrite_string(
+        str, request_mapping, URI.method(:encode_www_form_component)
+      )
     end
 
     def rewrite_request_query_string(env)
@@ -33,7 +35,8 @@ module Rack
     end
 
     def rewrite_request_path(env)
-      env['REQUEST_URI']  = rewrite_request_string(env['REQUEST_URI'])
+      env['PATH_INFO']   = rewrite_request_string(env['PATH_INFO'])
+      env['REQUEST_URI'] = rewrite_request_string(env['REQUEST_URI'])
     end
 
     def rewrite_string(string, mapping, transform = proc { |x| x })
@@ -60,23 +63,31 @@ module Rack
       status, headers, body = triplet
       rewrite_response_location headers
       remove_interfering_response_headers headers
-      [status, headers, body]
+      body = rewrite_response_body(body)
+      headers['Content-Length'] = body.size.to_s
+      [status, headers, [body]]
     end
 
     def rewrite_response_location(headers)
-      if headers['location']
-        headers['location'] = headers['location'].map do |location|
-          rewrite_string(location, _response_mapping)
-        end
+      return unless headers['location']
+
+      headers['location'] = headers['location'].map do |location|
+        rewrite_string(location, _response_mapping)
       end
     end
 
     def remove_interfering_response_headers(headers)
       headers.reject! do |key, _|
-        %w[status connection transfer-encoding].include?(key)
+        %w(status connection transfer-encoding).include?(key)
       end
     end
 
+    def rewrite_response_body(body)
+      str = rewrite_string(body.to_s, _response_mapping)
+      rewrite_string(str, _response_mapping,
+                     URI.method(:encode_www_form_component))
+    end
+
     def request_mapping
       fail 'Not implemented'
     end

data/rack-translating_proxy.gemspec

@@ -3,22 +3,23 @@ lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
-  spec.name          = "rack-translating_proxy"
-  spec.version       = '0.1.0'
-  spec.authors       = ["Mike Nicholaides"]
-  spec.email         = ["mike.nicholaides@gmail.com"]
+  spec.name          = 'rack-translating_proxy'
+  spec.version       = '0.1.1'
+  spec.authors       = ['Mike Nicholaides']
+  spec.email         = ['mike.nicholaides@gmail.com']
   spec.summary       = 'Proxy that translates strings'
   spec.description   = 'Proxy that translates strings'
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  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.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-proxy', '~> 0.5'
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rubocop', '0.25'
 end

data/spec/example_target_host.rb

@@ -0,0 +1,65 @@
+require 'sinatra'
+require 'base64'
+require 'json'
+
+get '/a-GET-request' do
+  'here is my GET request'
+end
+
+get '/' do
+  'here is my GET request to /'
+end
+
+get '/a-path' do
+  'a GET request to /'
+end
+
+post '/' do
+  params.inspect
+end
+
+put '/' do
+  params.inspect
+end
+
+delete '/' do
+  params.inspect
+end
+
+patch '/' do
+  params.inspect
+end
+
+### a redirect scenario
+get '/a-redirect' do
+  redirect '/redirected-page'
+end
+
+get '/redirected-page' do
+  'the redirected page'
+end
+
+get '/rewritten-path' do
+  'You are at /rewritten-path'
+end
+
+get '/page' do
+  params.inspect
+end
+
+post '/page' do
+  params.inspect
+end
+
+get '/page-with-stuff' do
+  '<a href="http://localhost/rewritten-path?rewrote+with+SPACE">' \
+  'rewrote with SPACE'
+end
+
+get '/reflect' do
+  Base64.encode64(params.to_json)
+end
+
+post '/reflect' do
+  Base64.encode64(params.to_json)
+end

data/spec/example_translating_proxy.rb

@@ -0,0 +1,17 @@
+require 'rack/translating_proxy'
+
+class ExampleTranslatingProxy < Rack::TranslatingProxy
+  def target_host
+    'http://localhost:5556'
+  end
+
+  def request_mapping
+    {
+      # the proxy                what the target host thinks it is
+      'http://localhost:5555' => 'http://localhost',
+
+      'rewritable' => 'rewritten',
+      'rewrite with space' => 'rewrote with SPACE'
+    }
+  end
+end

data/spec/example_translating_proxy.ru

@@ -0,0 +1,3 @@
+require 'example_translating_proxy'
+
+run ExampleTranslatingProxy.new

data/spec/integration_spec.rb

@@ -0,0 +1,95 @@
+require 'faraday'
+require 'json'
+require 'base64'
+
+describe 'proxying' do
+  let(:proxy_host) { 'http://localhost:5555' }
+
+  let(:http) do
+    Faraday.new(url: proxy_host) do |faraday|
+      faraday.request :url_encoded
+      faraday.adapter Faraday.default_adapter
+    end
+  end
+
+  %w(  get post put patch delete  ).each do |http_method|
+    define_method(http_method) do |*args|
+      @last_response = http.public_send(http_method, *args)
+    end
+  end
+
+  attr_reader :last_response
+
+  specify 'a GET request to /' do
+    get '/'
+    expect(last_response).to be_success
+    expect(last_response.body).to include 'here is my GET request to /'
+  end
+
+  specify 'a GET request' do
+    get '/a-GET-request'
+    expect(last_response).to be_success
+    expect(last_response.body).to include 'here is my GET request'
+  end
+
+  specify 'a POST request' do
+    post '/', 'the' => 'data'
+    expect(last_response).to be_success
+    expect(last_response.body).to include({ 'the' => 'data' }.inspect)
+  end
+
+  specify 'a PUT request' do
+    put '/', 'the' => 'data'
+    expect(last_response).to be_success
+    expect(last_response.body).to include({ 'the' => 'data' }.inspect)
+  end
+
+  specify 'a PATCH request' do
+    patch '/', 'the' => 'data'
+    expect(last_response).to be_success
+    expect(last_response.body).to include({ 'the' => 'data' }.inspect)
+  end
+
+  specify 'a DELETE request' do
+    delete '/', 'the' => 'data'
+    expect(last_response).to be_success
+    expect(last_response.body).to include({ 'the' => 'data' }.inspect)
+  end
+
+  specify 'handling a redirect' do
+    get '/a-redirect'
+    expect(last_response.headers['location']).to eq 'http://localhost:5555/redirected-page'
+    expect(last_response.status).to be 302
+  end
+
+  context 'on a request' do
+    let(:reflected_params) do
+      # encoded as Base64 so it's not de-translated on the way back
+      JSON.parse(Base64.decode64(last_response.body))
+    end
+
+    specify 'rewriting the path' do
+      get '/rewritable-path'
+      expect(last_response).to be_success
+    end
+
+    specify 'rewriting the query string' do
+      get '/reflect?rewrite+with+space=something'
+      expect(reflected_params).to include 'rewrote with SPACE' => 'something'
+    end
+
+    specify 'rewriting body contents' do
+      post '/reflect', 'rewrite with space' => 'something'
+      expect(reflected_params).to include 'rewrote with SPACE' => 'something'
+    end
+  end
+
+  context 'on a response' do
+    specify 'rewriting links in a page' do
+      get '/page-with-stuff'
+      expect(last_response.body).to eq \
+        '<a href="http://localhost:5555/rewritable-path?rewrite+with+space">' \
+        'rewrite with space'
+    end
+  end
+end

data/spec/script/example_target_host

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -e
+
+if [ "$1" == "fast" ]; then
+  runner="ruby"
+else
+  runner="shotgun"
+fi
+
+set -x
+bundle exec $runner spec/example_target_host.rb -p 5556

data/spec/script/example_translating_proxy

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -e
+
+if [ "$1" == "fast" ]; then
+  runner="rackup"
+else
+  runner="shotgun"
+fi
+
+set -x
+bundle exec $runner -I ./spec -p 5555 spec/example_translating_proxy.ru

data/spec/spec_helper.rb

@@ -2,9 +2,7 @@ RSpec.configure do |config|
   config.filter_run :focus
   config.run_all_when_everything_filtered = true
 
-  if config.files_to_run.one?
-    config.default_formatter = 'doc'
-  end
+  config.default_formatter = 'doc' if config.files_to_run.one?
 
   config.order = :random
 

data/spec/{translating_proxy_spec.rb → unit_spec.rb}

@@ -15,27 +15,32 @@ end
 describe ExampleTranslatingProxy do
   let(:app) { described_class.new }
 
-  describe "#rewrite_env" do
+  describe '#rewrite_env' do
     subject { app.rewrite_env(Hash.new { '' }.merge(env)) }
     let(:env) { {} }
 
-    describe "rewriting the uri" do
+    describe 'rewriting the uri' do
       its(['HTTP_HOST'])       { is_expected.to eq 'target-host.url' }
       its(['SERVER_PORT'])     { is_expected.to eq 443 }
       its(['rack.url_scheme']) { is_expected.to eq 'https' }
     end
 
-    describe "rewriting the path" do
+    describe 'rewriting the PATH_INFO' do
+      let(:env) { { 'PATH_INFO' => '/path/with/a+word' } }
+      its(['PATH_INFO']) { is_expected.to eq '/path/with/another+word' }
+    end
+
+    describe 'rewriting the REQUEST_URI' do
       let(:env) { { 'REQUEST_URI' => '/path/with/a+word' } }
       its(['REQUEST_URI']) { is_expected.to eq '/path/with/another+word' }
     end
 
-    describe "rewriting the query string" do
+    describe 'rewriting the query string' do
       let(:env) { { 'QUERY_STRING' => 'a+word&something-else' } }
       its(['QUERY_STRING']) { is_expected.to eq 'another+word&something-else' }
     end
 
-    describe "rewriting the body" do
+    describe 'rewriting the body' do
       context 'when it is a string' do
         let(:env) { { 'rack.input' => 'my+string+with+a+word' } }
         specify do
@@ -56,12 +61,12 @@ describe ExampleTranslatingProxy do
     end
   end
 
-  describe "#rewrite_response" do
+  describe '#rewrite_response' do
     subject { app.rewrite_response(triplet) }
 
     let(:triplet) { [given_status, given_headers, given_body] }
     let(:given_status)  { double }
-    let(:given_body)    { double }
+    let(:given_body)    { '' }
     let(:given_headers) do
       {
         'location' => %w(
@@ -69,22 +74,33 @@ describe ExampleTranslatingProxy do
           https://target.url:8765/path
         ),
 
-        'status'            => ["302 Found"],
+        'status'            => ['302 Found'],
         'connection'        => ['close'],
-        'transfer-encoding' => ["chunked"]
+        'transfer-encoding' => ['chunked']
       }
     end
 
     let(:rewritten_status)  { subject[0] }
     let(:rewritten_headers) { subject[1] }
-    let(:rewritten_body)    { subject[2] }
+    let(:rewritten_body)    { subject[2].join }
 
     specify { expect(rewritten_body).to eq given_body }
     specify { expect(rewritten_status).to eq given_status }
 
     specify do
-      expect(rewritten_headers).to eq \
-        'location' => %w(http://proxy.url:1234/path http://proxy.url:5678/path)
+      expect(rewritten_headers['location']).to eq \
+        %w(http://proxy.url:1234/path http://proxy.url:5678/path)
+    end
+
+    context 'when the body needs to be rewritten' do
+      let(:given_body) { 'another word' }
+      specify { expect(rewritten_body).to eq 'a word' }
+    end
+
+    context 'when the body needs to be rewritten with URL encoded stuff' do
+      let(:given_body) { 'another+word' }
+      specify { expect(rewritten_body).to eq 'a+word' }
+      specify { expect(rewritten_headers['Content-Length']).to eq '6' }
     end
   end
 end

metadata

@@ -1,57 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: rack-translating_proxy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mike Nicholaides
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-18 00:00:00.000000000 Z
+date: 2014-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack-proxy
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.25'
 description: Proxy that translates strings
 email:
 - mike.nicholaides@gmail.com
@@ -59,16 +73,24 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/rack/translating_proxy.rb
 - rack-translating_proxy.gemspec
+- spec/example_target_host.rb
+- spec/example_translating_proxy.rb
+- spec/example_translating_proxy.ru
+- spec/integration_spec.rb
+- spec/script/example_target_host
+- spec/script/example_translating_proxy
 - spec/spec_helper.rb
-- spec/translating_proxy_spec.rb
+- spec/unit_spec.rb
 homepage: ''
 licenses:
 - MIT
@@ -79,12 +101,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
@@ -94,5 +116,11 @@ signing_key:
 specification_version: 4
 summary: Proxy that translates strings
 test_files:
+- spec/example_target_host.rb
+- spec/example_translating_proxy.rb
+- spec/example_translating_proxy.ru
+- spec/integration_spec.rb
+- spec/script/example_target_host
+- spec/script/example_translating_proxy
 - spec/spec_helper.rb
-- spec/translating_proxy_spec.rb
+- spec/unit_spec.rb