telecaster 0.1.1

data/README.rdoc

@@ -0,0 +1,111 @@
+= Telecaster
+
+A multiplexing HTTP proxy based on EventMachine. Forwards every incoming request
+onto a set of backend servers, collects the responses and sends a summary back
+to the client.
+
+This is designed to allow independent services to notify each other about
+changes without tightly coupling them. Each service just calls a Telecaster
+server, which knows where to forward things to. The publisher gets a summary of
+which services were called and how they responded, which makes this notification
+style easier to debug than async message-passing systems.
+
+Telecaster supports delegation, so requests can be distributed to slaves and all
+the backend responses will be aggregated by the master.
+
+
+== Usage
+
+We recommend an EventMachine-based server like Thin, to best take advantage of
+EventMachine's concurrency. Create a Telecaster with a list of backend hosts and
+a logger:
+
+  require 'telecaster'
+  require 'logger'
+  
+  telecaster = Telecaster.new(
+    :backends => %w[http://concerts-service http://accounts-service],
+    :logger   => Logger.new($stdout)
+  )
+
+Then either boot it directly with Thin:
+
+  require 'rack'
+  Rack::Handler.get('thin').run(telecaster, :Port => 9000)
+
+or use a +rackup+ script
+
+  # config.ru
+  run telecaster
+  
+  $ thin start -R config.ru -p 9000
+
+
+== Protocol
+
+On every request, Telecaster returns a 200 response containing a JSON summary of
+the backend responses, for example:
+
+  $ curl localhost:9000/hello
+  [
+    {
+      "host": "http://localhost:9001",
+      "status": 200,
+      "duration": 16,
+      "data": {
+        "status": "ok"
+      }
+    },
+    {
+      "host": "http://localhost:9002",
+      "status": 200,
+      "duration": 16
+    },
+    {
+      "host": "http://localhost:9003",
+      "status": 404,
+      "duration": 15
+    }
+  ]
+
+This JSON list contains a record for each backend that was called. Each record
+contains the following fields:
+
+* +host+ - the hostname of the backend server
+* +status+ - a numetic HTTP status code if a response was received, else +nil+
+* +duration+ - the request time in milliseconds
+* +data+ - any JSON data returned by the backend
+
+Every backend may return a JSON object using <tt>Content-Type:
+application/json</tt>. If it does so, the data is included in the Telecaster
+summary.
+
+If the backend returns a JSON array, this is interpretted as Telecaster summary
+data and merged in - this is how Telecaster aggregates responses from delegate
+servers. So if you want to return custom data, the root of the response must be
+a single JSON object.
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2012 Songkick.com
+
+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/example/servers.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require File.expand_path('../../lib/telecaster', __FILE__)
+require File.expand_path('../../spec/backends', __FILE__)
+
+require 'logger'
+require 'thin'
+Thin::Logging.silent = true
+
+EM.run {
+  Rack::Handler.get('thin').run(Responder, :Port => 9001)
+  Rack::Handler.get('thin').run(Blank, :Port => 9002)
+  Rack::Handler.get('thin').run(Error, :Port => 9003)
+  
+  hosts = (1..3).map { |n| "http://localhost:900#{n}" }
+  logger = Logger.new($stdout)
+  telecaster = Telecaster.new(:backends => hosts, :logger => logger)
+  
+  Rack::Handler.get('thin').run(telecaster, :Port => 9000)
+}
+

data/lib/telecaster.rb

@@ -0,0 +1,83 @@
+require 'eventmachine'
+require 'em-http-request'
+require 'yajl'
+
+class Telecaster
+  ASYNC_RESPONSE = [-1, {}, []].freeze
+  TYPE_JSON      = 'application/json'
+  
+  ROOT = File.expand_path('..', __FILE__)
+  autoload :Multi, ROOT + '/telecaster/multi'
+  
+  def initialize(options)
+    @backend_hosts = options[:backends]
+    @logger = options[:logger]
+  end
+  
+  def call(env)
+    ensure_reactor_running
+    
+    method    = env['REQUEST_METHOD'].downcase
+    multi     = Multi.new
+    callback  = env['async.callback']
+    start     = Time.now.to_f
+    
+    @backend_hosts.each do |host|
+      request, args = *create_request(env, host)
+      multi.add(host, request.__send__(method, args))
+    end
+    
+    multi.callback do |response|
+      duration = ((Time.now.to_f - start) * 1000).round
+      summary = response.map { |r| '[' + [r['host'], r['status'], r['duration']] * ' ' + ']' }
+      @logger.info "#{env['REQUEST_METHOD']} #{env['REQUEST_URI']} backends:#{response.size} duration:#{duration} #{summary * ' '}"
+      
+      json = Yajl::Encoder.encode(response, :pretty => true, :indent => '  ')
+      callback.call [200, {'Content-Type' => TYPE_JSON}, [json]]
+    end
+    
+    ASYNC_RESPONSE
+    
+  rescue => e
+    [500, {'Content-Type' => 'text/plain'}, [e.message]]
+  end
+  
+private
+  
+  def create_request(env, host)
+    uri     = File.join(host, env['REQUEST_URI'])
+    request = EM::HttpRequest.new(uri)
+    args    = {:head => {}}
+    
+    env.each do |header, value|
+      next unless header =~ /^HTTP_/ and header != 'HTTP_HOST'
+      
+      name = header.gsub(/^HTTP_/, '').gsub('_', '-').
+                    downcase.
+                    gsub(/(^|-)([a-z])/) { $1 + $2.upcase }
+      
+      args[:head][name] = value
+    end
+    
+    if length = env['CONTENT_LENGTH']
+      args[:head]['Content-Length'] = length
+    end
+    
+    if type = env['CONTENT_TYPE']
+      args[:head]['Content-Type'] = type
+    end
+    
+    if input = env['rack.input']
+      args[:body] = input.read
+    end
+    
+    [request, args]
+  end
+  
+  def ensure_reactor_running
+    return if EM.reactor_running?
+    Thread.new { EM.run }
+    Thread.pass until EM.reactor_running?
+  end
+end
+

data/lib/telecaster/multi.rb

@@ -0,0 +1,54 @@
+# This is Telecaster::Multi, not a multitelecaster.
+# http://farm4.static.flickr.com/3068/2369563217_bd2c623c53.jpg
+
+class Telecaster
+  class Multi
+    include EM::Deferrable
+    
+    def initialize
+      @requests  = {}
+      @responses = {}
+    end
+    
+    def add(host, request)
+      start_time = Time.now.to_f
+      @requests[host] = request
+      
+      request.callback do |http|
+        response = {
+          'host'      => host,
+          'status'    => http.response_header.status,
+          'duration'  => ((Time.now.to_f - start_time) * 1000).round
+        }
+        content_type = (http.response_header['CONTENT_TYPE'] || '').split(/\s*;\s*/).first
+        
+        if content_type == TYPE_JSON
+          response['data'] = Yajl::Parser.parse(http.response)
+        end
+        @responses[host] = response
+        succeed if @responses.size == @requests.size
+      end
+      
+      request.errback do |http|
+        response = {'host' => host, 'status' => nil}
+        @responses[host] = response
+        succeed if @responses.size == @requests.size
+      end
+    end
+    
+  private
+    
+    def succeed
+      responses = []
+      @responses.each do |host, response|
+        if Array === response['data']
+          responses.concat(response['data'])
+        else
+          responses << response
+        end
+      end
+      super responses.sort_by { |r| r['host'] }
+    end
+  end
+end
+

data/spec/backends.rb

@@ -0,0 +1,48 @@
+require 'sinatra'
+
+class Responder < Sinatra::Base
+  before do
+    headers 'Content-Type' => 'application/json'
+  end
+  
+  get '/hello' do
+    Yajl::Encoder.encode('status' => 'ok')
+  end
+  
+  get '/error' do
+    status 503
+    Yajl::Encoder.encode('error' => 'down')
+  end
+  
+  get '/users/:username' do |username|
+    Yajl::Encoder.encode('username' => username)
+  end
+  
+  get '/search' do
+    Yajl::Encoder.encode('query' => params[:q])
+  end
+  
+  put '/blog' do
+    status 201
+    Yajl::Encoder.encode('title' => params[:title])
+  end
+end
+
+class Blank < Sinatra::Base
+  get '/hello' do
+    ''
+  end
+end
+
+class Slow < Sinatra::Base
+  get '/hello' do
+    EM.add_timer 2 do
+      env['async.callback'].call [200, {}, []]
+    end
+    [-1, {}, []]
+  end
+end
+
+class Error < Sinatra::Base
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'bundler/setup'
+require File.expand_path('../../lib/telecaster', __FILE__)
+
+require 'rack/proxy'
+require 'rack/test'
+require 'uri'
+
+require File.expand_path('../../vendor/em-rspec/lib/em-rspec', __FILE__)
+require File.expand_path('../telecaster_steps', __FILE__)
+
+class Proxy < Rack::Proxy
+  def initialize(host)
+    super()
+    @uri = URI.parse(host)
+  end
+  
+  def rewrite_env(env)
+    env['SERVER_NAME'] = @uri.host
+    env['SERVER_PORT'] = @uri.port.to_s
+    env['HTTP_HOST']   = [@uri.host, @uri.port].join(':')
+    env
+  end
+end
+

data/spec/telecaster_spec.rb

@@ -0,0 +1,159 @@
+require "spec_helper"
+require "backends"
+require "logger"
+
+describe Telecaster do
+  include TelecasterSteps
+  
+  let(:logger) { Logger.new(StringIO.new) }
+  
+  before do
+    Thread.new { EM.run }
+    Thread.pass until EM.reactor_running?
+  end
+  
+  after { stop_all_servers }
+  
+  describe "with a backend" do
+    let :app do
+      Proxy.new("http://localhost:9000")
+    end
+    
+    before do
+      telecaster = Telecaster.new(:backends => ["http://localhost:9001"], :logger => logger)
+      boot telecaster, 9000
+      
+      boot Responder, 9001
+    end
+    
+    after { sync }
+    
+    it "forwards a GET request" do
+      get "/hello", {}
+      check_status 200
+      check_json [{
+        "host"      => "http://localhost:9001",
+        "status"    => 200,
+        "duration"  => an_instance_of(Fixnum),
+        "data"      => {"status" => "ok"}
+      }]
+    end
+    
+    it "forwards a GET request with path params" do
+      get "/users/jcoglan", {}
+      check_status 200
+      check_json [{
+        "host"      => "http://localhost:9001",
+        "status"    => 200,
+        "duration"  => an_instance_of(Fixnum),
+        "data"      => {"username" => "jcoglan"}
+      }]
+    end
+    
+    it "forwards a GET request with query string params" do
+      get "/search?q=foo", {}
+      check_status 200
+      check_json [{
+        "host"      => "http://localhost:9001",
+        "status"    => 200,
+        "duration"  => an_instance_of(Fixnum),
+        "data"      => {"query" => "foo"}
+      }]
+    end
+    
+    it "forwards a PUT request with entity body params" do
+      put "/blog", :title => "A new post"
+      check_status 200
+      check_json [{
+        "host"      => "http://localhost:9001",
+        "status"    => 201,
+        "duration"  => an_instance_of(Fixnum),
+        "data"      => {"title" => "A new post"}
+      }]
+    end
+    
+    it "returns an error response" do
+      get "/error", {}
+      check_status 200
+      check_json [{
+        "host"      => "http://localhost:9001",
+        "status"    => 503,
+        "duration"  => an_instance_of(Fixnum),
+        "data"      => {"error" => "down"}
+      }]
+    end
+  end
+  
+  describe "with a backend that's down" do
+    let :app do
+      Proxy.new("http://localhost:9000")
+    end
+    
+    before do
+      telecaster = Telecaster.new(:backends => ["http://localhost:9001"], :logger => logger)
+      boot telecaster, 9000
+    end
+    
+    after { sync }
+    
+    it "returns a response with no status" do
+      get "/hello", {}
+      check_status 200
+      check_json [{ "host" => "http://localhost:9001", "status" => nil }]
+    end
+  end
+  
+  describe "with multiple backends" do
+    let :app do
+      Proxy.new("http://localhost:9000")
+    end
+    
+    before do
+      hosts = (1..3).map { |n| "http://localhost:900#{n}" }
+      telecaster = Telecaster.new(:backends => hosts, :logger => logger)
+      
+      boot telecaster, 9000
+      
+      boot Responder, 9001
+      boot Blank,     9002
+      boot Error,     9003
+    end
+    
+    after { sync }
+    
+    it "returns the responses from the backends" do
+      get "/hello", {}
+      check_status 200
+      check_json [
+        { "host" => "http://localhost:9001", "status" => 200, "duration" => an_instance_of(Fixnum), "data" => {"status" => "ok"} },
+        { "host" => "http://localhost:9002", "status" => 200, "duration" => an_instance_of(Fixnum) },
+        { "host" => "http://localhost:9003", "status" => 404, "duration" => an_instance_of(Fixnum) }
+      ]
+    end
+    
+    describe "delegation" do
+      let :app do
+        Proxy.new("http://localhost:9005")
+      end
+      
+      before do
+        telecaster = Telecaster.new(:backends => [0,4].map { |n| "http://localhost:900#{n}" }, :logger => logger)
+        boot telecaster, 9005
+        
+        boot Slow, 9004
+      end
+      
+      it "aggregates responses from delegate servers" do
+        get "/hello", {}
+        check_status 200
+        check_json [
+          { "host" => "http://localhost:9001", "status" => 200, "duration" => an_instance_of(Fixnum), "data" => {"status" => "ok"} },
+          { "host" => "http://localhost:9002", "status" => 200, "duration" => an_instance_of(Fixnum) },
+          { "host" => "http://localhost:9003", "status" => 404, "duration" => an_instance_of(Fixnum) },
+          { "host" => "http://localhost:9004", "status" => 200, "duration" => an_instance_of(Fixnum) }
+        ]
+      end
+    end
+  end
+end
+

data/spec/telecaster_steps.rb

@@ -0,0 +1,55 @@
+TelecasterSteps = EM::RSpec.async_steps do
+  include Rack::Test::Methods
+  
+  def boot(application, port, &callback)
+    @apps ||= {}
+    @apps[port] = application
+    application.extend(ThinRunner)
+    application.start(port)
+    EM.next_tick(&callback)
+  end
+  
+  def stop_all_servers(&callback)
+    @apps.each_value { |app| app.stop }
+    EM.next_tick(&callback)
+  end
+  
+  %w[get post put delete].each do |method|
+    class_eval %Q{
+      def #{method}(path, params, &callback)
+        EM.defer {
+          super(path, params)
+          callback.call
+        }
+      end
+    }
+  end
+  
+  def check_status(status, &callback)
+    last_response.status.to_i.should == status
+    callback.call
+  end
+  
+  def check_json(json, &callback)
+    last_response['Content-Type'].should == 'application/json'
+    Yajl::Parser.parse(last_response.body).should == json
+    callback.call
+  end
+end
+
+require 'thin'
+Thin::Logging.silent = true
+
+module ThinRunner
+  def start(port)
+    handler = Rack::Handler.get('thin')
+    handler.run(self, :Port => port) do |server|
+      @server = server
+    end
+  end
+  
+  def stop
+    @server.stop
+  end
+end
+

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: telecaster
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- James Coglan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: em-http-request
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+- !ruby/object:Gem::Dependency
+  name: rack-proxy
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+description: 
+email: james@songkick.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- README.rdoc
+- example/servers.rb
+- lib/telecaster/multi.rb
+- lib/telecaster.rb
+- spec/backends.rb
+- spec/spec_helper.rb
+- spec/telecaster_spec.rb
+- spec/telecaster_steps.rb
+homepage: http://github.com/songkick/telecaster
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: HTTP proxy for forwarding to multiple backends and collecting results
+test_files: []
+has_rdoc: