goliath 0.9.2 → 0.9.4

data/Gemfile

@@ -1,3 +1,3 @@
 source "http://rubygems.org"
 
-gemspec
+gemspec

data/{HISTORY → HISTORY.md}

@@ -1,33 +1,48 @@
-HISTORY
-=======
+# HISTORY
+
+## v0.9.3 (Oct 16, 2011)
+
+  - new router DSL - much improved, see examples
+  - refactored async_aroundware
+  - make jruby friendlier (removed 1.9 req in gemspec)
+  - enable epoll
+  - SSL support
+  - unix socket support
+  - reload config on HUP
+  - and a number of small bugfixes + other improvements..
+  - See full list @ https://github.com/postrank-labs/goliath/compare/v0.9.2...v0.9.3
+
+## v0.9.2 (July 21, 2011)
+
+  - See full list @ https://github.com/postrank-labs/goliath/compare/v0.9.1...v0.9.2
+
+## v0.9.1 (Apr 12, 2011)
 
-v0.9.1 (Apr 12, 2011)
----------------------
   - Added extra messaging around the class not matching the file name (Carlos Brando)
-  
+
   - Fix issue with POST parameters not being parsed by Goliath::Rack::Params
   - Added support for multipart encoded POST bodies
   - Added support for parsing nested query string parameters (Nolan Evans)
   - Added support for parsing application/json POST bodies
   - Content-Types outside of multipart, urlencoded and application/json will not be parsed automatically.
-  
+
   - added 'run as user' option
   - SERVER_NAME and SERVER_PORT are set to values in HOST header
-  
+
   - Cleaned up spec examples (Justin Ko)
-  
+
   - moved logger into 'rack.logger' key to be more Rack compliant (Env#logger added to
     keep original API consistent)
   - add command line option for specifying config file
   - HTTP_CONTENT_LENGTH and HTTP_CONTENT_TYPE were changed to CONTENT_TYPE and CONTENT_LENGTH
     to be more Rack compliant
   - fix issue with loading config file in development mode
-  
+
   - Rack::Reloader will be loaded automatically by the framework in development mode.
 
 
-v0.9.0 (Mar 9, 2011)
---------------------
+## v0.9.0 (Mar 9, 2011)
+
 (Initial Public Release)
 
 Goliath is an open source version of the non-blocking (asynchronous) Ruby web server framework
@@ -47,4 +62,3 @@ internal and external applications. Many of the Goliath processes have been runn
 a time (read: no memory leaks) and have served hundreds of gigabytes of data without restarts. To
 scale up and provide failover and redundancy, our individual Goliath servers at PostRank are usually
 deployed behind a reverse proxy (such as HAProxy).
-

data/README.md

@@ -20,18 +20,23 @@ Each HTTP request within Goliath is executed in its own Ruby fiber and all async
 
 ## Getting Started: Hello World
 
-    require 'goliath'
+```ruby
+require 'goliath'
 
-    class Hello < Goliath::API
-      def response(env)
-        [200, {}, "Hello World"]
-      end
-    end
+class Hello < Goliath::API
+  def response(env)
+    [200, {}, "Hello World"]
+  end
+end
 
-    > ruby hello.rb -sv
-    > [97570:INFO] 2011-02-15 00:33:51 :: Starting server on 0.0.0.0:9000 in development mode. Watch out for stones.
+> ruby hello.rb -sv
+> [97570:INFO] 2011-02-15 00:33:51 :: Starting server on 0.0.0.0:9000 in development mode. Watch out for stones.
+```
 
-See examples directory for more, hands-on examples of building Goliath powered web-services.
+See examples directory for more, hands-on examples of building Goliath powered web-services. Are you new to EventMachine, or want a detailed walk-through of building a Goliath powered API? You're in luck, we have two super-awesome peepcode screencasts which will teach you all you need to know:
+
+* [Meet EventMachine: Part 1](http://peepcode.com/products/eventmachine) - introduction to EM, Fibers, etc.
+* [Meet EventMachine: Part 2](http://peepcode.com/products/eventmachine-ii) - building an API with Goliath
 
 ## Performance: MRI, JRuby, Rubinius
 
@@ -52,7 +57,7 @@ Goliath has been in production at PostRank for over a year, serving a sustained
     * Mongrel is a threaded web-server, and both Passenger and Unicorn fork an entire VM to isolate each request from each other. By contrast, Goliath builds a single instance of the Rack app and runs all requests in parallel through a single VM, which leads to a much smaller memory footprint and less overhead.
 
 * How do I deploy Goliath in production?
-    * We recommend deploying Goliath behind a reverse proxy such as HAProxy, Nginx or equivalent. Using one of the above, you can easily run multiple instances of the same application and load balance between them within the reverse proxy.
+    * We recommend deploying Goliath behind a reverse proxy such as HAProxy ([sample config](https://github.com/postrank-labs/goliath/wiki/HAProxy)), Nginx or equivalent. Using one of the above, you can easily run multiple instances of the same application and load balance between them within the reverse proxy.
 
 ## Guides
 
@@ -63,6 +68,7 @@ Goliath has been in production at PostRank for over a year, serving a sustained
 
 ### Hands-on applications:
 
+* [Peepcode](http://peepcode.com/products/eventmachine) [screencasts](http://peepcode.com/products/eventmachine-ii)
 * [Asynchronous HTTP, MySQL, etc](https://github.com/postrank-labs/goliath/wiki/Asynchronous-Processing)
 * [Response streaming with Goliath](https://github.com/postrank-labs/goliath/wiki/Streaming)
 * [Examples](https://github.com/postrank-labs/goliath/tree/master/examples)
@@ -85,3 +91,4 @@ Goliath has been in production at PostRank for over a year, serving a sustained
 ## License & Acknowledgments
 
 Goliath is distributed under the MIT license, for full details please see the LICENSE file.
+Rock favicon CC-BY from [Douglas Feer](http://www.favicon.cc/?action=icon&file_id=375421)

data/examples/api_proxy.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+# Rewrites and proxies requests to a third-party API, with HTTP basic authentication.
+
+require 'goliath'
+require 'em-synchrony/em-http'
+ 
+class TwilioResponse < Goliath::API
+  use Goliath::Rack::Params
+  use Goliath::Rack::JSONP
+
+  HEADERS = { authorization: ENV.values_at("TWILIO_SID","TWILIO_AUTH_TOKEN") }
+  BASE_URL = "https://api.twilio.com/2010-04-01/Accounts/#{ENV['TWILIO_SID']}/AvailablePhoneNumbers/US"
+
+  def response(env)
+    url = "#{BASE_URL}#{env['REQUEST_PATH']}?#{env['QUERY_STRING']}"
+    logger.debug "Proxying #{url}"
+
+    http = EM::HttpRequest.new(url).get head: HEADERS
+    logger.debug "Received #{http.response_header.status} from Twilio"
+ 
+    [200, {'X-Goliath' => 'Proxy','Content-Type' => 'application/javascript'}, http.response]
+  end
+end
+
+class Twilio < Goliath::API
+  get %r{^/(Local|TollFree)}, TwilioResponse
+end

data/examples/async_aroundware_demo.rb

@@ -12,11 +12,11 @@ require 'yajl/json_gem'
 #
 # To run this, start the 'test_rig.rb' server on port 9002:
 #
-#   ./examples/test_rig.rb -sv -p 9002
+#   bundle exec ./examples/test_rig.rb -sv -p 9002
 #
 # And then start this server on port 9000:
 #
-#   ./async_aroundware_demo.rb -sv -p 9000
+#   bundle exec ./examples/barrier_aroundware_demo.rb -sv -p 9000
 #
 # Now curl the async_aroundware_demo_multi:
 #
@@ -42,27 +42,31 @@ require 'yajl/json_gem'
 
 BASE_URL     = 'http://localhost:9002/'
 
-class MyResponseReceiver < Goliath::Synchrony::MultiReceiver
+class RemoteRequestBarrier
+  include Goliath::Rack::BarrierAroundware
+  attr_accessor :sleep_1
+  
   def pre_process
     # Request with delay_1 and drop_1 -- note: 'aget', because we want execution to continue
     req = EM::HttpRequest.new(BASE_URL).aget(:query => { :delay => env.params['delay_1'], :drop => env.params['drop_1'] })
-    add :sleep_1, req
+    enqueue :sleep_1, req
+    return Goliath::Connection::AsyncResponse
   end
 
   def post_process
     # unify the results with the results of the API call
-    responses[:callback].each{|name, resp| body[:results][name] = JSON.parse(resp.response) }
-    responses[:errback ].each{|name, err|  body[:errors][name]  = err.error     }
-    [status, headers, JSON.generate(body)]
+    if successes.include?(:sleep_1) then body[:results][:sleep_1] = JSON.parse(sleep_1.response)
+    else                                 body[:errors][:sleep_1]  = sleep_1.error     ; end
+    [status, headers, JSON.pretty_generate(body)]
   end
 end
 
-class AsyncAroundwareDemo < Goliath::API
+class BarrierAroundwareDemo < Goliath::API
   use Goliath::Rack::Params
   use Goliath::Rack::Validation::NumericRange, {:key => 'delay_1', :default => 1.0, :max => 5.0, :min => 0.0, :as => Float}
   use Goliath::Rack::Validation::NumericRange, {:key => 'delay_2', :default => 0.5, :max => 5.0, :min => 0.0, :as => Float}
   #
-  use Goliath::Rack::AsyncAroundware, MyResponseReceiver
+  use Goliath::Rack::BarrierAroundwareFactory, RemoteRequestBarrier
 
   def response(env)
     # Request with delay_2 and drop_2 -- note: 'get', because we want execution to proceed linearly
@@ -71,7 +75,7 @@ class AsyncAroundwareDemo < Goliath::API
     body = { :results => {}, :errors => {} }
 
     if resp.response_header.status.to_i != 0
-      body[:results][:sleep_2] = JSON.parse(resp.response)
+      body[:results][:sleep_2] = JSON.parse(resp.response) rescue 'parsing failed'
     else
       body[:errors ][:sleep_2] = resp.error
     end

data/examples/auth_and_rate_limit.rb

@@ -4,46 +4,115 @@ require 'goliath'
 require 'em-mongo'
 require 'em-http'
 require 'em-synchrony/em-http'
+require 'em-synchrony/em-mongo'
 require 'yajl/json_gem'
 
-require 'goliath/synchrony/mongo_receiver'            # has the aroundware logic for talking to mongodb
 require File.join(File.dirname(__FILE__), 'http_log') # Use the HttpLog as our actual endpoint, but include this in the middleware
 
+#
 # Usage:
 #
-# First launch a dummy responder, like hello_world.rb or test_rig.rb:
-# ruby ./examples/hello_world.rb -sv -p 8080 -e prod &
+# First launch the test rig:
+#     bundle exec ./examples/test_rig.rb -sv -p 8080 -e prod &
 #
 # Then launch this script
-# ruby ./examples/auth_and_rate_limit.rb -sv -p 9000 --config $PWD/examples/config/auth_and_rate_limit.rb
+#     bundle exec ./examples/auth_and_rate_limit.rb -sv -p 9000 --config $PWD/examples/config/auth_and_rate_limit.rb
+#
+# The auth info is returned in the headers:
+#
+#   curl -vv 'http://127.0.0.1:9000/?_apikey=i_am_busy&drop=false' ; echo
+#   ...snip...
+#   < X-RateLimit-MaxRequests: 1000
+#   < X-RateLimit-Requests: 999
+#   < X-RateLimit-Reset: 1312059600
+#
+# This user will hit the rate limit after 10 requests:
+#
+#     for foo in 1 2 3 4 5 6 7 8 9 10 11 12 ; do echo -ne $foo "\t" ; curl 'http://127.0.0.1:9000/?_apikey=i_am_limited' ; echo ; done
+#     1   {"Special":"Header","Params":"_apikey: i_am_awesome|drop: false","Path":"/","Headers":"User-Agent: ...
+#     ...
+#     11  [:error, "Your request rate (11) is over your limit (10)"]
+#
+# You can test the barrier (both delays are in fractional seconds):
+# * drop=true     will drop the request at the remote host
+# * auth_db_delay will fake a slow response from the mongo
+# * delay         will cause a slow response from the remote host
+#
+#     time curl -vv 'http://127.0.0.1:9000/?_apikey=i_am_awesome&drop=false&delay=0.4&auth_db_delay=0.3'
+#     ...
+#     X-Tracer: ... received_usage_info: 0.06, received_sleepy: 299.52, received_downstream_resp: 101.67, ..., total: 406.09
+#     ...
+#     real      0m0.416s        user    0m0.002s        sys     0m0.003s        pct     1.24
+#
+# This shows the mongodb response returning quickly, the fake DB delay returning
+# after 300ms, and the downstream response returning after an additional 101 ms.
+# The total request took 416ms of wall-clock time
+#
+# This will hold up even in the face of many concurrent connections. Relaunch in
+# production (you may have to edit the config/auth_and_rate_limit scripts):
+#
+#     bundle exec ./examples/auth_and_rate_limit.rb -sv -p 9000 -e prod --config $PWD/examples/config/auth_and_rate_limit.rb
+#
+# On my laptop, with 20 concurrent requests (each firing two db gets, a 400 ms
+# http get, and two db writes), the median/90%ile times were 431ms / 457ms:
+#
+#     time ab -c20 -n20 'http://127.0.0.1:9000/?_apikey=i_am_awesome&drop=false&delay=0.4&auth_db_delay=0.3'
+#     ...
+#     Percentage of the requests served within a certain time (ms)
+#     50%    431
+#     90%    457
+#     real      0m0.460s        user    0m0.001s        sys     0m0.003s        pct     0.85
+#
+# With 100 concurrent requests, the request latency starts to drop but the
+# throughput and variance stand up:
+#
+#     time ab -c100 -n100 'http://127.0.0.1:9000/?_apikey=i_am_awesome&drop=false&delay=0.4&auth_db_delay=0.3'
+#     ...
+#     Percentage of the requests served within a certain time (ms)
+#     50%    640
+#     90%    673
+#     real      0m0.679s        user    0m0.002s        sys     0m0.007s        pct     1.33
 #
 
 # Tracks and enforces account and rate limit policies.
 #
-# Before the request:
+# This is like a bouncer who lets townies order a drink while he checks their
+# ID, but who's a jerk to college kids.
 #
-# * validates the apikey exists
-# * launches requests for the account and current usage (hourly rate limit, etc)
+# On GET or HEAD requests, it proxies the request and gets account/usage info
+# concurrently; authorizing the account doesn't delay the response.
 #
-# It then passes the request down the middleware chain; execution resumes only
-# when both the remote request and the auth info have returned.
+# On a POST or other non-idempotent request, it checks the account/usage info
+# *before* allowing the request to fire. This takes longer, but is necessary and
+# tolerable.
 #
-# After remote request and auth info return:
+# The magic of BarrierAroundware:
 #
-# * Check the account exists and is valid
-# * Check the rate limit is OK
+# 1) In pre_process (before the request):
+#    * validate an apikey was given; if not, raise (returning directly)
+#    * launch requests for the account and rate limit usage
 #
-# If it passes all those checks, the request goes through; otherwise we raise an
-# error that Goliath::Rack::Validator turns into a 4xx response
+# 2) On a POST or other non-GET non-HEAD, we issue `perform`, which barriers
+#    (allowing other requests to proceed) until the two pending requests
+#    complete. It then checks the account exists and is valid, and that the rate
+#    limit is OK
 #
-# WARNING: Since this passes ALL requests through to the responder, it's only
-# suitable for idempotent requests (GET, typically).  You may need to handle
-# POST/PUT/DELETE requests differently.
+# 3) If the auth check fails, we raise an error (later caught by a safely{}
+#    block and turned into the right 4xx HTTP response.
 #
+# 4) If the auth check succeeds, or the request is a GET or HEAD, we return
+#    Goliath::Connection::AsyncResponse, and BarrierAroundwareFactory passes the
+#    request down the middleware chain
 #
-class AuthReceiver < Goliath::Synchrony::MongoReceiver
+# 5) post_process resumes only when both proxied request & auth info are complete
+#    (it already has of course in the non-lazy scenario)
+#
+# 6) If we were lazy, the post_process method now checks authorization
+#
+class AuthBarrier
+  include Goliath::Rack::BarrierAroundware
   include Goliath::Validation
-  include Goliath::Rack::Validator
+  attr_reader   :db
   attr_accessor :account_info, :usage_info
 
   # time period to aggregate stats over, in seconds
@@ -53,36 +122,84 @@ class AuthReceiver < Goliath::Synchrony::MongoReceiver
   class RateLimitExceededError < ForbiddenError    ; end
   class InvalidApikeyError     < UnauthorizedError ; end
 
+  def initialize(env, db_name)
+    @db = env.config[db_name]
+    super(env)
+  end
+
   def pre_process
+    env.trace('pre_process_beg')
     validate_apikey!
-    first('AccountInfo', { :_id => apikey   }){|res| self.account_info = res }
-    first('UsageInfo',   { :_id => usage_id }){|res| self.usage_info   = res }
+
+    # the results of the afirst deferrable will be set right into account_info (and the request into successes)
+    enqueue_mongo_request(:account_info, { :_id => apikey   })
+    enqueue_mongo_request(:usage_info,   { :_id => usage_id })
+    maybe_fake_delay!
+
+    # On non-GET non-HEAD requests, we have to check auth now.
+    unless lazy_authorization?
+      perform     # yield execution until user_info has arrived
+      charge_usage
+      check_authorization!
+    end
+
     env.trace('pre_process_end')
+    return Goliath::Connection::AsyncResponse
   end
 
   def post_process
     env.trace('post_process_beg')
-    env.logger.info [account_info, usage_info].inspect
-    self.account_info ||= {}
-    self.usage_info   ||= {}
+    # [:account_info, :usage_info, :status, :headers, :body].each{|attr| env.logger.info(("%23s\t%s" % [attr, self.send(attr).inspect[0..200]])) }
 
     inject_headers
 
-    EM.next_tick do
-      safely(env){ charge_usage }
+    # We have to check auth now, we skipped it before
+    if lazy_authorization?
+      charge_usage
+      check_authorization!
     end
 
-    safely(env, headers) do
-      check_apikey!
-      check_rate_limit!
+    env.trace('post_process_end')
+    [status, headers, body]
+  end
+
+  def lazy_authorization?
+    (env['REQUEST_METHOD'] == 'GET') || (env['REQUEST_METHOD'] == 'HEAD')
+  end
+
+  if defined?(EM::Mongo::Cursor)
+    # em-mongo > 0.3.6 gives us a deferrable back. nice and clean.
+    def enqueue_mongo_request(handle, query)
+      enqueue handle, db.collection(handle).afirst(query)
+    end
+  else
+    # em-mongo <= 0.3.6 makes us fake a deferrable response.
+    def enqueue_mongo_request(handle, query)
+      enqueue_acceptor(handle) do |acc|
+        db.collection(handle).afind(query){|resp| acc.succeed(resp.first) }
+      end
+    end
+  end
 
-      env.trace('post_process_end')
-      [status, headers, body]
+  # Fake out a delay in the database response if auth_db_delay is given
+  def maybe_fake_delay!
+    if (auth_db_delay = env.params['auth_db_delay'].to_f) > 0
+      enqueue_acceptor(:sleepy){|acc| EM.add_timer(auth_db_delay){ acc.succeed } }
     end
   end
 
+  def accept_response(handle, *args)
+    env.trace("received_#{handle}")
+    super(handle, *args)
+  end
+
   # ===========================================================================
 
+  def check_authorization!
+    check_apikey!
+    check_rate_limit!
+  end
+
   def validate_apikey!
     if apikey.to_s.empty?
       raise MissingApikeyError
@@ -90,25 +207,30 @@ class AuthReceiver < Goliath::Synchrony::MongoReceiver
   end
 
   def check_apikey!
-    unless account_info['valid'] == true
+    unless account_info && (account_info['valid'] == true)
       raise InvalidApikeyError
     end
   end
 
   def check_rate_limit!
-    return true if usage_info['calls'].to_f <= account_info['max_call_rate'].to_f
-    raise RateLimitExceededError
+    self.usage_info ||= {}
+    rate  = usage_info['calls'].to_i + 1
+    limit = account_info['max_call_rate'].to_i
+    return true if rate <= limit
+    raise RateLimitExceededError, "Your request rate (#{rate}) is over your limit (#{limit})"
   end
 
   def charge_usage
-    update('UsageInfo', { :_id => usage_id },
-      { '$inc' => { :calls   => 1 } }, :upsert => true)
+    EM.next_tick do
+      safely(env){ db.collection(:usage_info).update({ :_id => usage_id },
+          { '$inc' => { :calls   => 1 } }, :upsert => true) }
+    end
   end
 
   def inject_headers
     headers.merge!({
         'X-RateLimit-MaxRequests' => account_info['max_call_rate'].to_s,
-        'X-RateLimit-Requests'    => usage_info['calls'].to_s,
+        'X-RateLimit-Requests'    => usage_info['calls'].to_i.to_s,
         'X-RateLimit-Reset'       => timebin_end.to_s,
       })
   end
@@ -139,5 +261,5 @@ end
 class AuthAndRateLimit < HttpLog
   use Goliath::Rack::Tracer, 'X-Tracer'
   use Goliath::Rack::Params             # parse & merge query and body parameters
-  use Goliath::Rack::AsyncAroundware, AuthReceiver, 'api_auth_db'
+  use Goliath::Rack::BarrierAroundwareFactory, AuthBarrier, 'api_auth_db'
 end