rainbows 0.1.1 → 0.2.0

data/.document

@@ -1,11 +1,12 @@
-README
-LICENSE
+ChangeLog
 DEPLOY
+FAQ
 lib
-rainbows.1
-ChangeLog
+LICENSE
 NEWS
+rainbows.1
+README
+SIGNALS
 TODO
-FAQ
 TUNING
 vs_Unicorn

data/DEPLOY

@@ -27,3 +27,16 @@ processing of the request body as it is being uploaded.
 
 In this case, haproxy or any similar (non-request-body-buffering) load
 balancer should be used to balance requests between different machines.
+
+== Denial-of-Service Concerns
+
+Since \Rainbows! is designed to talk to slow clients with long-held
+connections, it may be subject to brute force denial-of-service attacks.
+In Unicorn and Mongrel, we've already enabled the "httpready" accept
+filter for FreeBSD and the TCP_DEFER_ACCEPT option in Linux; but it is
+still possible to build clients that work around and fool these
+mechanisms.
+
+\Rainbows! itself does not feature any explicit protection against brute
+force denial-of-service attacks.  We believe this is best handled by
+dedicated firewalls provided by the operating system.

data/GIT-VERSION-GEN

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 GVF=GIT-VERSION-FILE
-DEF_VER=v0.1.1.GIT
+DEF_VER=v0.2.0.GIT
 
 LF='
 '

data/GNUmakefile

@@ -58,7 +58,7 @@ NEWS: GIT-VERSION-FILE
 	$(rake) -s news_rdoc > $@+
 	mv $@+ $@
 
-SINCE =
+SINCE = 0.1.1
 ChangeLog: log_range = $(shell test -n "$(SINCE)" && echo v$(SINCE)..)
 ChangeLog: GIT-VERSION-FILE
 	@echo "ChangeLog from $(GIT_URL) ($(SINCE)..$(GIT_VERSION))" > $@+

data/README

@@ -16,11 +16,21 @@ For network concurrency, models we currently support are:
 * {:ThreadSpawn}[link:Rainbows/ThreadSpawn.html]
 * {:ThreadPool}[link:Rainbows/ThreadPool.html]
 * {:Revactor}[link:Rainbows/Revactor.html]
+* {:Rev}[link:Rainbows/Rev.html]*
 
 We have {more on the way}[link:TODO.html] for handling network concurrency.
 Additionally, we also use multiple processes (managed by Unicorn) for
 CPU/memory/disk concurrency.
 
+\* our \Rev concurrency model is only recommended for slow clients, not
+sleepy apps.  Additionally it does not support streaming "rack.input" to
+the application.
+
+For application concurrency, we have the Rainbows::AppPool Rack
+middleware that allows us to limit application concurrency independently
+of network concurrency.  Rack::Lock as distributed by Rack may also be
+used to limit application concurrency to one (per-worker).
+
 == Features
 
 * Designed for {Rack}[http://rack.rubyforge.org/], the standard for
@@ -54,6 +64,9 @@ CPU/memory/disk concurrency.
 * Long polling
 * Reverse Ajax
 
+\Rainbows may also be used to service slow clients even with fast
+applications using the \Rev concurrency model.
+
 == License
 
 \Rainbows! is copyright 2009 by all contributors (see logs in git).
@@ -99,13 +112,25 @@ config file:
 
     Rainbows! do
       use :Revactor
-      worker_connections 128
+      worker_connections 400
     end
 
+See the {Rainbows! configuration documentation}[link:Rainbows.html#M000001]
+for more details.
+
 == Development
 
-* git: git://git.bogomips.org/rainbows.git
-* cgit: http://git.bogomips.org/cgit/rainbows.git
+You can get the latest source via git from the following locations
+(these versions may not be stable):
+
+  git://git.bogomips.org/rainbows.git
+  git://rubyforge.org/rainbows.git (mirror)
+
+You may browse the code from the web and download the latest snapshot
+tarballs here:
+
+* http://git.bogomips.org/cgit/rainbows.git (cgit)
+* http://rainbows.rubyforge.org/git?p=rainbows.git (gitweb)
 
 Inline patches (from "git format-patch") to the mailing list are
 preferred because they allow code review and comments in the reply to
@@ -126,9 +151,10 @@ and we'll try our best to fix it.
 All feedback (bug reports, user/development dicussion, patches, pull
 requests) go to the mailing list/newsgroup.  Patches must be sent inline
 (git format-patch -M + git send-email).  No subscription is necessary
-to post on the mailing list.  No top posting.  Address replies +To:+ (or
-+Cc:+) the original sender and +Cc:+ the mailing list.
+to post on the mailing list.  No top posting.  Address replies +To:+
+the mailing list.
 
 * email: mailto:rainbows-talk@rubyforge.org
-* archives: http://rubyforge.org/pipermail/rainbows-talk
+* nntp: nntp://news.gmane.org/gmane.comp.lang.ruby.rainbows.general
 * subscribe: http://rubyforge.org/mailman/listinfo/rainbows-talk
+* archives: http://rubyforge.org/pipermail/rainbows-talk

data/SIGNALS

@@ -2,7 +2,10 @@
 
 In general, signals need only be sent to the master process.  However,
 the signals Rainbows! uses internally to communicate with the worker
-processes are documented here as well.
+processes are documented here as well.  With the exception of TTIN/TTOU,
+signal handling matches the behavior of and {nginx}[http://nginx.net/]
+so it should be possible to easily share process management scripts
+between \Rainbows!, Unicorn and nginx.
 
 === Master Process
 
@@ -43,16 +46,17 @@ automatically respawned.
 
 * USR1 - Reopen all logs owned by the worker process.
   See Unicorn::Util.reopen_logs for what is considered a log.
-  Log files are not reopened until it is done processing
-  the current request, so multiple log lines for one request
-  (as done by Rails) will not be split across multiple logs.
+  Unlike Unicorn, log files are reopened immediately in \Rainbows!
+  since worker processes are likely to be serving multiple clients
+  simutaneously, we can't wait for all of them to finish.
 
 === Procedure to replace a running rainbows executable
 
-You may replace a running instance of unicorn with a new one without
+You may replace a running instance of rainbows with a new one without
 losing any incoming connections.  Doing so will reload all of your
-application code, Unicorn config, Ruby executable, and all libraries.
-The only things that will not change (due to OS limitations) are:
+application code, Unicorn/Rainbows! config, Ruby executable, and all
+libraries.  The only things that will not change (due to OS limitations)
+are:
 
 1. The path to the rainbows executable script.  If you want to change to
    a different installation of Ruby, you can modify the shebang

data/TODO

@@ -3,9 +3,8 @@
 We're lazy and pick the easy items to do first, then the ones people
 care about.
 
-* Rev (without Revactor) - since we already use Revactor we might as
-  well support this one so 1.8 users won't be left out.  Doing TeeInput
-  is probably going to get ugly, though...
+* Rev + Thread - current Rev model with threading, which will give
+  us a streaming (but rewindable) "rack.input".
 
 * EventMachine - much like Rev, but we haven't looked at this one much
   (our benevolent dictator doesn't like C++).  If we can figure out how

data/lib/rainbows.rb

@@ -7,6 +7,7 @@ module Rainbows
   require 'rainbows/http_server'
   require 'rainbows/http_response'
   require 'rainbows/base'
+  autoload :AppPool, 'rainbows/app_pool'
 
   class << self
 
@@ -17,18 +18,23 @@ module Rainbows
     end
   end
 
-  # configures Rainbows! with a given concurrency model to +use+ and
+  # configures \Rainbows! with a given concurrency model to +use+ and
   # a +worker_connections+ upper-bound.  This method may be called
   # inside a Unicorn/Rainbows configuration file:
   #
   #   Rainbows! do
   #     use :Revactor # this may also be :ThreadSpawn or :ThreadPool
-  #     worker_connections 128
+  #     worker_connections 400
   #   end
   #
+  #   # the rest of the Unicorn configuration
+  #   worker_processes 8
+  #
   # See the documentation for the respective Revactor, ThreadSpawn,
   # and ThreadPool classes for descriptions and recommendations for
-  # each of them.
+  # each of them.  The total number of clients we're able to serve is
+  # +worker_processes+ * +worker_connections+, so in the above example
+  # we can serve 8 * 400 = 3200 clients concurrently.
   def Rainbows!(&block)
     block_given? or raise ArgumentError, "Rainbows! requires a block"
     HttpServer.setup(block)
@@ -42,6 +48,7 @@ module Rainbows
     :Revactor => 50,
     :ThreadSpawn => 30,
     :ThreadPool => 10,
+    :Rev => 50,
   }.each do |model, _|
     u = model.to_s.gsub(/([a-z0-9])([A-Z0-9])/) { "#{$1}_#{$2.downcase!}" }
     autoload model, "rainbows/#{u.downcase!}"

data/lib/rainbows/app_pool.rb

@@ -0,0 +1,90 @@
+# -*- encoding: binary -*-
+
+require 'thread'
+
+module Rainbows
+
+  # Rack middleware to limit application-level concurrency independently
+  # of network conncurrency in \Rainbows!   Since the +worker_connections+
+  # option in \Rainbows! is only intended to limit the number of
+  # simultaneous clients, this middleware may be used to limit the
+  # number of concurrent application dispatches independently of
+  # concurrent clients.
+  #
+  # Instead of using M:N concurrency in \Rainbows!, this middleware
+  # allows M:N:P concurrency where +P+ is the AppPool +:size+ while
+  # +M+ remains the number of +worker_processes+ and +N+ remains the
+  # number of +worker_connections+.
+  #
+  #   rainbows master
+  #    \_ rainbows worker[0]
+  #    |  \_ client[0,0]------\      ___app[0]
+  #    |  \_ client[0,1]-------\    /___app[1]
+  #    |  \_ client[0,2]-------->--<       ...
+  #    |  ...                __/    `---app[P]
+  #    |  \_ client[0,N]----/
+  #    \_ rainbows worker[1]
+  #    |  \_ client[1,0]------\      ___app[0]
+  #    |  \_ client[1,1]-------\    /___app[1]
+  #    |  \_ client[1,2]-------->--<       ...
+  #    |  ...                __/    `---app[P]
+  #    |  \_ client[1,N]----/
+  #    \_ rainbows worker[M]
+  #       \_ client[M,0]------\      ___app[0]
+  #       \_ client[M,1]-------\    /___app[1]
+  #       \_ client[M,2]-------->--<       ...
+  #       ...                __/    `---app[P]
+  #       \_ client[M,N]----/
+  #
+  # AppPool should be used if you want to enforce a lower value of +P+
+  # than +N+.
+  #
+  # AppPool has no effect on the Rainbows::Rev concurrency model as that is
+  # single-threaded/single-instance as far as application concurrency goes.
+  # In other words, +P+ is always +one+ when using \Rev (but not
+  # \Revactor) regardless of (or even if) this middleware is loaded.
+  #
+  # Since this is Rack middleware, you may load this in your Rack
+  # config.ru file and even use it in servers other than \Rainbows!
+  #
+  #   use Rainbows::AppPool, :size => 30
+  #   map "/lobster" do
+  #     run Rack::Lobster.new
+  #   end
+  #
+  # You may to load this earlier or later in your middleware chain
+  # depending on the concurrency/copy-friendliness of your middleware(s).
+
+  class AppPool < Struct.new(:pool)
+
+    # +opt+ is a hash, +:size+ is the size of the pool (default: 6)
+    # meaning you can have up to 6 concurrent instances of +app+
+    # within one \Rainbows! worker process.  We support various
+    # methods of the +:copy+ option: +dup+, +clone+, +deep+ and +none+.
+    # Depending on your +app+, one of these options should be set.
+    # The default +:copy+ is +:dup+ as is commonly seen in existing
+    # Rack middleware.
+    def initialize(app, opt = {})
+      self.pool = Queue.new
+      (1...(opt[:size] || 6)).each do
+        pool << case (opt[:copy] || :dup)
+        when :none then app
+        when :dup then app.dup
+        when :clone then app.clone
+        when :deep then Marshal.load(Marshal.dump(app)) # unlikely...
+        else
+          raise ArgumentError, "unsupported copy method: #{opt[:copy].inspect}"
+        end
+      end
+      pool << app # the original
+    end
+
+    # Rack application endpoint, +env+ is the Rack environment
+    def call(env)
+      app = pool.shift
+      app.call(env)
+      ensure
+        pool << app
+    end
+  end
+end

data/lib/rainbows/base.rb

@@ -2,7 +2,8 @@
 
 module Rainbows
 
-  # base class for Rainbows concurrency models
+  # base class for Rainbows concurrency models, this is currently
+  # used by ThreadSpawn and ThreadPool models
   module Base
 
     include Unicorn
@@ -16,16 +17,35 @@ module Rainbows
       client.close rescue nil
     end
 
+    # TODO: migrate into Unicorn::HttpServer
+    def listen_loop_error(e)
+      logger.error "Unhandled listen loop exception #{e.inspect}."
+      logger.error e.backtrace.join("\n")
+    end
+
+    def init_worker_process(worker)
+      super(worker)
+
+      # we're don't use the self-pipe mechanism in the Rainbows! worker
+      # since we don't defer reopening logs
+      HttpServer::SELF_PIPE.each { |x| x.close }.clear
+      trap(:USR1) { reopen_worker_logs(worker.nr) rescue nil }
+      # closing anything we IO.select on will raise EBADF
+      trap(:QUIT) { HttpServer::LISTENERS.map! { |s| s.close rescue nil } }
+      [:TERM, :INT].each { |sig| trap(sig) { exit!(0) } } # instant shutdown
+      logger.info "Rainbows! #@use worker_connections=#@worker_connections"
+    end
+
     # once a client is accepted, it is processed in its entirety here
     # in 3 easy steps: read request, call app, write app response
     def process_client(client)
       buf = client.readpartial(CHUNK_SIZE)
       hp = HttpParser.new
       env = {}
+      alive = true
       remote_addr = TCPSocket === client ? client.peeraddr.last : LOCALHOST
 
       begin # loop
-        Thread.current[:t] = Time.now
         while ! hp.headers(env, buf)
           buf << client.readpartial(CHUNK_SIZE)
         end
@@ -42,9 +62,10 @@ module Rainbows
           response = app.call(env)
         end
 
-        out = [ hp.keepalive? ? CONN_ALIVE : CONN_CLOSE ] if hp.headers?
+        alive = hp.keepalive? && ! Thread.current[:quit]
+        out = [ alive ? CONN_ALIVE : CONN_CLOSE ] if hp.headers?
         HttpResponse.write(client, response, out)
-      end while hp.keepalive? and hp.reset.nil? and env.clear
+      end while alive and hp.reset.nil? and env.clear
       client.close
     # if we get any error, try to write something back to the client
     # assuming we haven't closed the socket, but don't get hung up
@@ -60,6 +81,22 @@ module Rainbows
       logger.error e.backtrace.join("\n")
     end
 
+    def join_threads(threads, worker)
+      logger.info "Joining threads..."
+      threads.each { |thr| thr[:quit] = true }
+      t0 = Time.now
+      timeleft = timeout * 2.0
+      m = 0
+      while (nr = threads.count { |thr| thr.alive? }) > 0 && timeleft > 0
+        threads.each { |thr|
+          worker.tmp.chmod(m = 0 == m ? 1 : 0)
+          thr.join(1)
+          break if (timeleft -= (Time.now - t0)) < 0
+        }
+      end
+      logger.info "Done joining threads. #{nr} left running"
+    end
+
     def self.included(klass)
       klass.const_set :LISTENERS, HttpServer::LISTENERS
     end

data/lib/rainbows/const.rb

@@ -3,16 +3,11 @@
 module Rainbows
 
   module Const
-    RAINBOWS_VERSION = '0.1.1'
+    RAINBOWS_VERSION = '0.2.0'
 
     include Unicorn::Const
 
     RACK_DEFAULTS = ::Unicorn::HttpRequest::DEFAULTS.merge({
-
-      # we need to observe many of the rules for thread-safety even
-      # with Revactor or Rev, so we're considered multithread-ed even
-      # when we're not technically...
-      "rack.multithread" => true,
       "SERVER_SOFTWARE" => "Rainbows! #{RAINBOWS_VERSION}",
     })
 

data/lib/rainbows/http_server.rb

@@ -31,7 +31,7 @@ module Rainbows
       Module === mod or
         raise ArgumentError, "concurrency model #{model.inspect} not supported"
       extend(mod)
-      @use = model
+      Const::RACK_DEFAULTS['rainbows.model'] = @use = model
     end
 
     def worker_connections(*args)

data/lib/rainbows/rev.rb

@@ -0,0 +1,174 @@
+# -*- encoding: binary -*-
+require 'rev'
+
+# workaround revactor 0.1.4 still using the old Rev::Buffer
+# ref: http://rubyforge.org/pipermail/revactor-talk/2009-October/000034.html
+defined?(Rev::Buffer) or Rev::Buffer = IO::Buffer
+
+module Rainbows
+
+  # Implements a basic single-threaded event model with
+  # {Rev}[http://rev.rubyforge.org/].  It is capable of handling
+  # thousands of simultaneous client connections, but with only a
+  # single-threaded app dispatch.  It is suited for slow clients and
+  # fast applications (applications that do not have slow network
+  # dependencies).  It does not require your Rack application to
+  # be reentrant or thread-safe.
+  #
+  # Compatibility: Whatever \Rev itself supports, currently Ruby
+  # 1.8/1.9.
+  #
+  # This model does not implement as streaming "rack.input" which
+  # allows the Rack application to process data as it arrives.  This
+  # means "rack.input" will be fully buffered in memory or to a
+  # temporary file before the application is entered.
+  #
+  # Caveats: this model can buffer all output for slow clients in
+  # memory.  This can be a problem if your application generates large
+  # responses (including static files served with Rack) as it will cause
+  # the memory footprint of your process to explode.  If your workers
+  # seem to be eating a lot of memory from this, consider the
+  # {mall}[http://bogomips.org/mall/] library which allows access to the
+  # mallopt(3) function from Ruby.
+
+  module Rev
+
+    # global vars because class/instance variables are confusing me :<
+    # this struct is only accessed inside workers and thus private to each
+    G = Struct.new(:nr, :max, :logger, :alive, :app).new
+
+    include Base
+
+    class Client < ::Rev::IO
+      include Unicorn
+      include Rainbows::Const
+      G = Rainbows::Rev::G
+
+      def initialize(io)
+        G.nr += 1
+        super(io)
+        @remote_addr = ::TCPSocket === io ? io.peeraddr.last : LOCALHOST
+        @env = {}
+        @hp = HttpParser.new
+        @state = :headers # [ :body [ :trailers ] ] :app_call :close
+        @buf = ""
+      end
+
+      def handle_error(e)
+        msg = case e
+        when EOFError,Errno::ECONNRESET,Errno::EPIPE,Errno::EINVAL,Errno::EBADF
+          ERROR_500_RESPONSE
+        when HttpParserError # try to tell the client they're bad
+          ERROR_400_RESPONSE
+        else
+          G.logger.error "Read error: #{e.inspect}"
+          G.logger.error e.backtrace.join("\n")
+          ERROR_500_RESPONSE
+        end
+        write(msg)
+        ensure
+          @state = :close
+      end
+
+      def app_call
+        @input.rewind
+        @env[RACK_INPUT] = @input
+        @env[REMOTE_ADDR] = @remote_addr
+        response = G.app.call(@env.update(RACK_DEFAULTS))
+        alive = @hp.keepalive? && G.alive
+        out = [ alive ? CONN_ALIVE : CONN_CLOSE ] if @hp.headers?
+        HttpResponse.write(self, response, out)
+        if alive
+          @env.clear
+          @hp.reset
+          @state = :headers
+        else
+          @state = :close
+        end
+      end
+
+      def on_write_complete
+        :close == @state and close
+      end
+
+      def on_close
+        G.nr -= 1
+      end
+
+      def tmpio
+        io = Util.tmpio
+        def io.size
+          # already sync=true at creation, so no need to flush before stat
+          stat.size
+        end
+        io
+      end
+
+      # TeeInput doesn't map too well to this right now...
+      def on_read(data)
+        case @state
+        when :headers
+          @hp.headers(@env, @buf << data) or return
+          @state = :body
+          len = @hp.content_length
+          if len == 0
+            @input = HttpRequest::NULL_IO
+            app_call # common case
+          else # nil or len > 0
+            # since we don't do streaming input, we have no choice but
+            # to take over 100-continue handling from the Rack application
+            if @env[HTTP_EXPECT] =~ /\A100-continue\z/i
+              write(EXPECT_100_RESPONSE)
+              @env.delete(HTTP_EXPECT)
+            end
+            @input = len && len <= MAX_BODY ? StringIO.new("") : tmpio
+            @hp.filter_body(@buf2 = @buf.dup, @buf)
+            @input << @buf2
+            on_read("")
+          end
+        when :body
+          if @hp.body_eof?
+            @state = :trailers
+            on_read(data)
+          elsif data.size > 0
+            @hp.filter_body(@buf2, @buf << data)
+            @input << @buf2
+            on_read("")
+          end
+        when :trailers
+          @hp.trailers(@env, @buf << data) and app_call
+        end
+        rescue Object => e
+          handle_error(e)
+      end
+    end
+
+    class Server < ::Rev::IO
+      G = Rainbows::Rev::G
+
+      def on_readable
+        return if G.nr >= G.max
+        begin
+          Client.new(@_io.accept_nonblock).attach(::Rev::Loop.default)
+        rescue Errno::EAGAIN, Errno::ECONNBORTED
+        end
+      end
+
+    end
+
+    # runs inside each forked worker, this sits around and waits
+    # for connections and doesn't die until the parent dies (or is
+    # given a INT, QUIT, or TERM signal)
+    def worker_loop(worker)
+      init_worker_process(worker)
+      G.nr = 0
+      G.max = worker_connections
+      G.alive = true
+      G.logger = logger
+      G.app = app
+      LISTENERS.map! { |s| Server.new(s).attach(::Rev::Loop.default) }
+      ::Rev::Loop.default.run
+    end
+
+  end
+end