rainbows 0.2.0 → 0.3.0

data/GIT-VERSION-GEN

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

data/TODO

@@ -3,6 +3,13 @@
 We're lazy and pick the easy items to do first, then the ones people
 care about.
 
+* Improve test suite coverage.  We won't waste cycles with puny
+  unit tests, only integration tests that exercise externally
+  visible parts.
+
+* (maybe) make our tests TAP-compatible.  Unfortunately the the
+  only shell library we've seen for TAP seems to use bashisms.
+
 * Rev + Thread - current Rev model with threading, which will give
   us a streaming (but rewindable) "rack.input".
 
@@ -10,6 +17,12 @@ care about.
   (our benevolent dictator doesn't like C++).  If we can figure out how
   to do Rev without Revactor, then this should be pretty easy.
 
+* EventMachine + catch/throw :async API used in Thin
+
+* EventMachine.spawn - should be like Revactor, maybe?
+
+* Rev + callcc - current Rev model with callcc (should work with MBARI)
+
 * Fiber support - Revactor already uses these with Ruby 1.9, also not
   sure how TeeInput can be done with this.
 
@@ -17,3 +30,5 @@ care about.
 
 * Rubinius Actors - should be like Revactor and easily doable once
   Rubinius gets more mature.
+
+* test and improve performance (throughput/latency/memory usage)

data/TUNING

@@ -7,6 +7,13 @@ of the time waiting on network activity.  Thus memory usage and memory
 bandwidth for keeping connections open are often limiting factors as
 well.
 
+As of October 2009, absolutely ZERO work has been done for performance
+validation and tuning.  Furthermore, \Rainbows! is NOT expected to do well on
+traditional benchmarks.  Remember that \Rainbows! is only designed for
+applications that sleep and/or trickle network traffic.  In the future,
+*may* do well in traditional benchmarks as a side effect, but that will
+never be the primary goal of the project.
+
 == \Rainbows! configuration
 
 * Don't set +worker_connections+ too high.  It is often better to start
@@ -18,6 +25,13 @@ well.
   robust against crashes and are more likely to be fairly scheduled by
   the kernel.
 
+* If your workers do not seem to be releasing memory to the OS after
+  traffic spikes, consider the {mall}[http://bogomips.org/mall/] library
+  which allows access to the mallopt(3) function from Ruby. As of
+  October 2009 tcmalloc (the default allocator for Ruby Enterprise
+  Edition) does not release memory back to the kernel, the best it can
+  do is use madvise(2) in an effort to swap out unused pages.
+
 == nginx configuration
 
 If you intend to use nginx as a reverse-proxy in front of \Rainbows!  to

data/lib/rainbows.rb

@@ -3,11 +3,18 @@ require 'unicorn'
 
 module Rainbows
 
+  # global vars because class/instance variables are confusing me :<
+  # this struct is only accessed inside workers and thus private to each
+  G = Struct.new(:cur, :max, :logger, :alive, :app).new
+  # G.cur may not be used the network concurrency model
+  G.alive = true
+
   require 'rainbows/const'
   require 'rainbows/http_server'
   require 'rainbows/http_response'
   require 'rainbows/base'
   autoload :AppPool, 'rainbows/app_pool'
+  autoload :DevFdResponse, 'rainbows/dev_fd_response'
 
   class << self
 

data/lib/rainbows/app_pool.rb

@@ -39,10 +39,11 @@ module Rainbows
   # 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
+  # AppPool has no effect on the 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.
+  # In other words, +P+ is always +one+ when using Rev.  AppPool currently
+  # only works with the ThreadSpawn and ThreadPool models.  It does not
+  # yet work reliably with the Revactor model, yet.
   #
   # Since this is Rack middleware, you may load this in your Rack
   # config.ru file and even use it in servers other than \Rainbows!

data/lib/rainbows/base.rb

@@ -8,6 +8,7 @@ module Rainbows
 
     include Unicorn
     include Rainbows::Const
+    G = Rainbows::G
 
     # write a response without caring if it went out or not for error
     # messages.
@@ -17,21 +18,28 @@ module Rainbows
       client.close rescue nil
     end
 
-    # TODO: migrate into Unicorn::HttpServer
     def listen_loop_error(e)
+      G.alive or return
       logger.error "Unhandled listen loop exception #{e.inspect}."
       logger.error e.backtrace.join("\n")
     end
 
     def init_worker_process(worker)
       super(worker)
+      G.cur = 0
+      G.max = worker_connections
+      G.logger = logger
+      G.app = app
 
       # 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 } }
+      trap(:QUIT) do
+        G.alive = false
+        # closing anything we IO.select on will raise EBADF
+        HttpServer::LISTENERS.map! { |s| s.close rescue nil }
+      end
       [:TERM, :INT].each { |sig| trap(sig) { exit!(0) } } # instant shutdown
       logger.info "Rainbows! #@use worker_connections=#@worker_connections"
     end
@@ -62,7 +70,7 @@ module Rainbows
           response = app.call(env)
         end
 
-        alive = hp.keepalive? && ! Thread.current[:quit]
+        alive = hp.keepalive? && G.alive
         out = [ alive ? CONN_ALIVE : CONN_CLOSE ] if hp.headers?
         HttpResponse.write(client, response, out)
       end while alive and hp.reset.nil? and env.clear
@@ -82,23 +90,21 @@ module Rainbows
     end
 
     def join_threads(threads, worker)
-      logger.info "Joining threads..."
-      threads.each { |thr| thr[:quit] = true }
-      t0 = Time.now
-      timeleft = timeout * 2.0
+      Rainbows::G.alive = false
+      expire = Time.now + (timeout * 2.0)
       m = 0
-      while (nr = threads.count { |thr| thr.alive? }) > 0 && timeleft > 0
+      while (nr = threads.count { |thr| thr.alive? }) > 0
         threads.each { |thr|
           worker.tmp.chmod(m = 0 == m ? 1 : 0)
           thr.join(1)
-          break if (timeleft -= (Time.now - t0)) < 0
+          break if Time.now >= expire
         }
       end
-      logger.info "Done joining threads. #{nr} left running"
     end
 
     def self.included(klass)
       klass.const_set :LISTENERS, HttpServer::LISTENERS
+      klass.const_set :G, Rainbows::G
     end
 
   end

data/lib/rainbows/const.rb

@@ -3,12 +3,16 @@
 module Rainbows
 
   module Const
-    RAINBOWS_VERSION = '0.2.0'
+    RAINBOWS_VERSION = '0.3.0'
 
     include Unicorn::Const
 
     RACK_DEFAULTS = ::Unicorn::HttpRequest::DEFAULTS.merge({
       "SERVER_SOFTWARE" => "Rainbows! #{RAINBOWS_VERSION}",
+
+      # using the Rev model, we'll automatically chunk pipe and socket objects
+      # if they're the response body
+      'rainbows.autochunk' => false,
     })
 
     CONN_CLOSE = "Connection: close\r\n"

data/lib/rainbows/dev_fd_response.rb

@@ -0,0 +1,69 @@
+# -*- encoding: binary -*-
+
+module Rainbows
+
+  # Rack response middleware wrapping any IO-like object with an
+  # OS-level file descriptor associated with it.  May also be used to
+  # create responses from integer file descriptors or existing +IO+
+  # objects.  This may be used in conjunction with the #to_path method
+  # on servers that support it to pass arbitrary file descriptors into
+  # the HTTP response without additional open(2) syscalls
+
+  class DevFdResponse < Struct.new(:app, :to_io, :to_path)
+    include Rack::Utils
+
+    # Rack middleware entry point, we'll just pass through responses
+    # unless they respond to +to_io+ or +to_path+
+    def call(env)
+      status, headers, body = response = app.call(env)
+
+      # totally uninteresting to us if there's no body
+      return response if STATUS_WITH_NO_ENTITY_BODY.include?(status)
+
+      io = body.to_io if body.respond_to?(:to_io)
+      io ||= File.open(body.to_path, 'rb') if body.respond_to?(:to_path)
+      return response if io.nil?
+
+      headers = HeaderHash.new(headers)
+      st = io.stat
+      if st.file?
+        headers['Content-Length'] ||= st.size.to_s
+        headers.delete('Transfer-Encoding')
+      elsif st.pipe? || st.socket? # epoll-able things
+        if env['rainbows.autochunk']
+          headers['Transfer-Encoding'] = 'chunked'
+          headers.delete('Content-Length')
+        else
+          headers['X-Rainbows-Autochunk'] = 'no'
+        end
+      else # unlikely, char/block device file, directory, ...
+        return response
+      end
+      resp = dup # be reentrant here
+      resp.to_path = "/dev/fd/#{io.fileno}"
+      resp.to_io = io
+      [ status, headers.to_hash, resp ]
+    end
+
+    # called by the webserver or other middlewares if they can't
+    # handle #to_path
+    def each(&block)
+      to_io.each(&block)
+    end
+
+    # remain Rack::Lint-compatible for people with wonky systems :P
+    unless File.exist?("/dev/fd/0")
+      alias to_path_orig to_path
+      undef_method :to_path
+    end
+
+    # called by the web server after #each
+    def close
+      begin
+        to_io.close if to_io.respond_to?(:close)
+      rescue IOError # could've been IO::new()'ed and closed
+      end
+    end
+
+  end # class
+end

data/lib/rainbows/http_response.rb

@@ -13,6 +13,7 @@ module Rainbows
         status = CODES[status.to_i] || status
 
         headers.each do |key, value|
+          next if %r{\AX-Rainbows-}i =~ key
           next if SKIP.include?(key.downcase)
           if value =~ /\n/
             out.concat(value.split(/\n/).map! { |v| "#{key}: #{v}\r\n" })

data/lib/rainbows/http_server.rb

@@ -32,6 +32,8 @@ module Rainbows
         raise ArgumentError, "concurrency model #{model.inspect} not supported"
       extend(mod)
       Const::RACK_DEFAULTS['rainbows.model'] = @use = model
+      Const::RACK_DEFAULTS['rack.multithread'] = !!(/Thread/ =~ model.to_s)
+      Const::RACK_DEFAULTS['rainbows.autochunk'] = (model.to_s == "Rev")
     end
 
     def worker_connections(*args)

data/lib/rainbows/rev.rb

@@ -12,8 +12,10 @@ module Rainbows
   # 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.
+  # dependencies) or applications that use DevFdResponse for deferrable
+  # response bodies.  It does not require your Rack application to be
+  # thread-safe, reentrancy is only required for the DevFdResponse body
+  # generator.
   #
   # Compatibility: Whatever \Rev itself supports, currently Ruby
   # 1.8/1.9.
@@ -22,39 +24,41 @@ module Rainbows
   # 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
+      G = Rainbows::G
+
+      # queued, optional response bodies, it should only be unpollable "fast"
+      # devices where read(2) is uninterruptable.  Unfortunately, NFS and ilk
+      # are also part of this.  We'll also stick DeferredResponse bodies in
+      # here to prevent connections from being closed on us.
+      attr_reader :deferred_bodies
 
       def initialize(io)
-        G.nr += 1
+        G.cur += 1
         super(io)
         @remote_addr = ::TCPSocket === io ? io.peeraddr.last : LOCALHOST
         @env = {}
         @hp = HttpParser.new
         @state = :headers # [ :body [ :trailers ] ] :app_call :close
         @buf = ""
+        @deferred_bodies = [] # for (fast) regular files only
+      end
+
+      # graceful exit, like SIGQUIT
+      def quit
+        @deferred_bodies.clear
+        @state = :close
       end
 
       def handle_error(e)
+        quit
         msg = case e
         when EOFError,Errno::ECONNRESET,Errno::EPIPE,Errno::EINVAL,Errno::EBADF
           ERROR_500_RESPONSE
@@ -66,33 +70,51 @@ module Rainbows
           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
+        begin
+          (@env[RACK_INPUT] = @input).rewind
+          alive = @hp.keepalive?
+          @env[REMOTE_ADDR] = @remote_addr
+          response = G.app.call(@env.update(RACK_DEFAULTS))
+          alive &&= G.alive
+          out = [ alive ? CONN_ALIVE : CONN_CLOSE ] if @hp.headers?
+
+          DeferredResponse.write(self, response, out)
+          if alive
+            @env.clear
+            @hp.reset
+            @state = :headers
+            # keepalive requests are always body-less, so @input is unchanged
+            @hp.headers(@env, @buf) and next
+          else
+            @state = :close
+          end
+          return
+        end while true
       end
 
       def on_write_complete
-        :close == @state and close
+        if body = @deferred_bodies.first
+          return if DeferredResponse === body
+          begin
+            begin
+              write(body.sysread(CHUNK_SIZE))
+            rescue EOFError # expected at file EOF
+              @deferred_bodies.shift
+              body.close
+            end
+          rescue Object => e
+            handle_error(e)
+          end
+        else
+          close if :close == @state
+        end
       end
 
       def on_close
-        G.nr -= 1
+        G.cur -= 1
       end
 
       def tmpio
@@ -144,10 +166,10 @@ module Rainbows
     end
 
     class Server < ::Rev::IO
-      G = Rainbows::Rev::G
+      G = Rainbows::G
 
       def on_readable
-        return if G.nr >= G.max
+        return if G.cur >= G.max
         begin
           Client.new(@_io.accept_nonblock).attach(::Rev::Loop.default)
         rescue Errno::EAGAIN, Errno::ECONNBORTED
@@ -156,18 +178,89 @@ module Rainbows
 
     end
 
+    class DeferredResponse < ::Rev::IO
+      include Unicorn
+      include Rainbows::Const
+      G = Rainbows::G
+
+      def self.defer!(client, response, out)
+        body = response.last
+        headers = Rack::Utils::HeaderHash.new(response[1])
+
+        # to_io is not part of the Rack spec, but make an exception
+        # here since we can't get here without checking to_path first
+        io = body.to_io if body.respond_to?(:to_io)
+        io ||= ::IO.new($1.to_i) if body.to_path =~ %r{\A/dev/fd/(\d+)\z}
+        io ||= File.open(File.expand_path(body.to_path), 'rb')
+        st = io.stat
+
+        if st.socket? || st.pipe?
+          do_chunk = !!(headers['Transfer-Encoding'] =~ %r{\Achunked\z}i)
+          do_chunk = false if headers.delete('X-Rainbows-Autochunk') == 'no'
+          # too tricky to support keepalive/pipelining when a response can
+          # take an indeterminate amount of time here.
+          out[0] = CONN_CLOSE
+
+          io = new(io, client, do_chunk, body).attach(::Rev::Loop.default)
+        elsif st.file?
+          headers.delete('Transfer-Encoding')
+          headers['Content-Length'] ||= st.size.to_s
+        else # char/block device, directory, whatever... nobody cares
+          return response
+        end
+        client.deferred_bodies << io
+        [ response.first, headers.to_hash, [] ]
+      end
+
+      def self.write(client, response, out)
+        response.last.respond_to?(:to_path) and
+          response = defer!(client, response, out)
+        HttpResponse.write(client, response, out)
+      end
+
+      def initialize(io, client, do_chunk, body)
+        super(io)
+        @client, @do_chunk, @body = client, do_chunk, body
+      end
+
+      def on_read(data)
+        @do_chunk and @client.write(sprintf("%x\r\n", data.size))
+        @client.write(data)
+        @do_chunk and @client.write("\r\n")
+      end
+
+      def on_close
+        @do_chunk and @client.write("0\r\n\r\n")
+        @client.quit
+        @body.respond_to?(:close) and @body.close
+      end
+    end
+
+    # This timer handles the fchmod heartbeat to prevent our master
+    # from killing us.
+    class Heartbeat < ::Rev::TimerWatcher
+      G = Rainbows::G
+
+      def initialize(tmp)
+        @m, @tmp = 0, tmp
+        super(1, true)
+      end
+
+      def on_timer
+        @tmp.chmod(@m = 0 == @m ? 1 : 0)
+        exit if (! G.alive && G.cur <= 0)
+      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
+      rloop = ::Rev::Loop.default
+      Heartbeat.new(worker.tmp).attach(rloop)
+      LISTENERS.map! { |s| Server.new(s).attach(rloop) }
+      rloop.run
     end
 
   end