rainbows 3.2.0 → 3.3.0

data/lib/rainbows/client.rb

@@ -4,19 +4,22 @@ require "io/wait"
 
 # this class is used for most synchronous concurrency models
 class Rainbows::Client < Kgio::Socket
+  include Rainbows::ProcessClient
+  Rainbows.config!(self, :keepalive_timeout)
+
   def read_expire
-    Time.now + Rainbows.keepalive_timeout
+    Time.now + KEEPALIVE_TIMEOUT
   end
 
   def kgio_wait_readable
-    wait Rainbows.keepalive_timeout
+    wait KEEPALIVE_TIMEOUT
   end
 
   # used for reading headers (respecting keepalive_timeout)
   def timed_read(buf)
     expire = nil
     begin
-      case rv = kgio_tryread(16384, buf)
+      case rv = kgio_tryread(CLIENT_HEADER_BUFFER_SIZE, buf)
       when :wait_readable
         return if expire && expire < Time.now
         expire ||= read_expire
@@ -26,6 +29,4 @@ class Rainbows::Client < Kgio::Socket
       end
     end while true
   end
-
-  include Rainbows::ProcessClient
 end

data/lib/rainbows/configurator.rb

@@ -2,49 +2,203 @@
 
 # This module adds \Rainbows! to the
 # {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
+# \Rainbows!-specific configuration options must be inside a the Rainbows!
+# block, otherwise Unicorn::Configurator directives may be used anwwhere
+# in the file.
+#
+#   Rainbows! do
+#     use :ThreadSpawn # concurrency model to use
+#     worker_connections 400
+#     keepalive_timeout 0 # zero disables keepalives entirely
+#     client_max_body_size 5*1024*1024 # 5 megabytes
+#     keepalive_requests 666 # default:100
+#     client_header_buffer_size 2 * 1024 # 2 kilobytes
+#   end
+#
+#   # the rest of the Unicorn configuration...
+#   worker_processes 8
+#   stderr_path "/path/to/error.log"
+#   stdout_path "/path/to/output.log"
 module Rainbows::Configurator
+  Unicorn::Configurator::DEFAULTS.merge!({
+    :use => Rainbows::Base,
+    :worker_connections => 50,
+    :keepalive_timeout => 5,
+    :keepalive_requests => 100,
+    :client_max_body_size => 1024 * 1024,
+    :client_header_buffer_size => 1024,
+    :copy_stream => IO.respond_to?(:copy_stream) ? IO : false,
+  })
 
-  # 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:
+  # Configures \Rainbows! with a given concurrency model to +use+ and
+  # a +worker_connections+ upper-bound.  This method should be called
+  # inside a Unicorn/\Rainbows! configuration file.
+  #
+  # All other methods in Rainbows::Configurator must be called
+  # inside this block.
+  def Rainbows!(&block)
+    block_given? or raise ArgumentError, "Rainbows! requires a block"
+    @block = true
+    instance_eval(&block)
+    ensure
+      @block = false
+  end
+
+  def check! # :nodoc:
+    @block or abort "must be inside a Rainbows! block"
+  end
+
+  # This limits the number of connected clients per-process.  The total
+  # number of clients on a server is +worker_processes+ * +worker_connections+.
+  #
+  # This option has no effect with the Base concurrency model, which is
+  # limited to +1+.
+  #
+  # Default: 50
+  def worker_connections(clients)
+    check!
+    set_int(:worker_connections, clients, 1)
+  end
+
+  # Select a concurrency model for use with \Rainbows!.  You must select
+  # this with a Symbol (prefixed with ":").  Thus if you wish to select
+  # the Rainbows::ThreadSpawn concurrency model, you would use:
   #
   #   Rainbows! do
-  #     use :ThreadSpawn # concurrency model to use
-  #     worker_connections 400
-  #     keepalive_timeout 0 # zero disables keepalives entirely
-  #     client_max_body_size 5*1024*1024 # 5 megabytes
-  #     keepalive_requests 666 # default:100
+  #     use :ThreadSpawn
   #   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.  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.
-  #
-  # The default is +keepalive_timeout+ is 5 seconds, which should be
-  # enough under most conditions for browsers to render the page and
-  # start retrieving extra elements for.  Increasing this beyond 5
-  # seconds is not recommended.  Zero disables keepalive entirely
-  # (but pipelining fully-formed requests is still works).
-  #
-  # The default +client_max_body_size+ is 1 megabyte (1024 * 1024 bytes),
-  # setting this to +nil+ will disable body size checks and allow any
-  # size to be specified.
-  #
-  # The default +keepalive_requests+ is 100, meaning a client may
-  # complete 100 keepalive requests after the initial request before
-  # \Rainbows! forces a disconnect.  Lowering this can improve
-  # load-balancing characteristics as it forces HTTP/1.1 clients to
-  # reconnect after the specified number of requests, hopefully to a
-  # less busy host or worker process.  This may also be used to mitigate
-  # denial-of-service attacks that use HTTP pipelining.
-  def Rainbows!(&block)
-    block_given? or raise ArgumentError, "Rainbows! requires a block"
-    Rainbows::HttpServer.setup(block)
+  # See the {Summary}[link:Summary.html] document for a summary of
+  # supported concurrency models.  +options+ may be specified for some
+  # concurrency models, but the majority do not support them.
+  #
+  # Default: :Base (no concurrency)
+  def use(model, *options)
+    check!
+    mod = begin
+      Rainbows.const_get(model)
+    rescue NameError => e
+      warn "error loading #{model.inspect}: #{e}"
+      e.backtrace.each { |l| warn l }
+      abort "concurrency model #{model.inspect} not supported"
+    end
+    Module === mod or abort "concurrency model #{model.inspect} not supported"
+    options.each do |opt|
+      case opt
+      when Hash
+        Rainbows::O.merge!(opt)
+      when Symbol
+        Rainbows::O[opt] = true
+      else
+        abort "cannot handle option: #{opt.inspect} in #{options.inspect}"
+      end
+    end
+    mod.setup if mod.respond_to?(:setup)
+    set[:use] = mod
+  end
+
+  # Sets the value (in seconds) the server will wait for a client in
+  # between requests.  The default value should be enough under most
+  # conditions for browsers to render the page and start retrieving
+  # extra elements.
+  #
+  # Setting this value to +0+ disables keepalive entirely
+  #
+  # Default: 5 seconds
+  def keepalive_timeout(seconds)
+    check!
+    set_int(:keepalive_timeout, seconds, 0)
+  end
+
+  # This limits the number of requests which can be made over a keep-alive
+  # connection.  This is used to prevent single client from monopolizing
+  # the server and to improve fairness when load-balancing across multiple
+  # machines by forcing a client to reconnect.  This may be helpful
+  # in mitigating some denial-of-service attacks.
+  #
+  # Default: 100 requests
+  def keepalive_requests(count)
+    check!
+    case count
+    when nil, Integer
+      set[:keepalive_requests] = count
+    else
+      abort "not an integer or nil: keepalive_requests=#{count.inspect}"
+    end
+  end
+
+  # Limits the maximum size of a request body for all requests.
+  # Setting this to +nil+ disables the maximum size check.
+  #
+  # Default: 1 megabyte (1048576 bytes)
+  #
+  # If you want endpoint-specific upload limits and use a
+  # "rack.input"-streaming concurrency model, see the Rainbows::MaxBody
+  def client_max_body_size(bytes)
+    check!
+    err = "client_max_body_size must be nil or a non-negative Integer"
+    case bytes
+    when nil
+    when Integer
+      bytes >= 0 or abort err
+    else
+      abort err
+    end
+    set[:client_max_body_size] = bytes
+  end
+
+  # This governs the amount of memory allocated for an individual read(2) or
+  # recv(2) system call when reading headers.  Applications that make minimal
+  # use of cookies should not increase this from the default.
+  #
+  # Rails applications using session cookies may want to increase this to
+  # 2048 bytes or more depending on expected request sizes.
+  #
+  # Increasing this will increase overall memory usage to your application,
+  # as you will need at least this amount of memory for every connected client.
+  #
+  # Default: 1024 bytes
+  def client_header_buffer_size(bytes)
+    check!
+    set_int(:client_header_buffer_size, bytes, 1)
+  end
+
+  # Allows overriding the +klass+ where the +copy_stream+ method is
+  # used to do efficient copying of regular files, pipes, and sockets.
+  #
+  # This is only used with multi-threaded concurrency models:
+  #
+  # * ThreadSpawn
+  # * ThreadPool
+  # * WriterThreadSpawn
+  # * WriterThreadPool
+  # * XEpollThreadSpawn
+  # * XEpollThreadPool
+  #
+  # Due to existing {bugs}[http://redmine.ruby-lang.org/search?q=copy_stream]
+  # in the Ruby IO.copy_stream implementation, \Rainbows! uses the
+  # "sendfile" RubyGem that instead of copy_stream to transfer regular files
+  # to clients.  The "sendfile" RubyGem also supports more operating systems,
+  # and works with more concurrency models.
+  #
+  # Recent Linux 2.6 users may override this with "IO::Splice" from the
+  # "io_splice" RubyGem:
+  #
+  #   require "io/splice"
+  #   Rainbows! do
+  #     copy_stream IO::Splice
+  #   end
+  #
+  # Keep in mind that splice(2) itself is a relatively new system call
+  # and has been buggy in many older Linux kernels.
+  #
+  # Default: IO on Ruby 1.9+, false otherwise
+  def copy_stream(klass)
+    check!
+    if klass && ! klass.respond_to?(:copy_stream)
+      abort "#{klass} must respond to `copy_stream' or be `false'"
+    end
+    set[:copy_stream] = klass
   end
 end
 

data/lib/rainbows/const.rb

@@ -2,7 +2,7 @@
 # :enddoc:
 module Rainbows::Const
 
-  RAINBOWS_VERSION = '3.2.0'
+  RAINBOWS_VERSION = '3.3.0'
 
   include Unicorn::Const
 

data/lib/rainbows/coolio.rb

@@ -21,6 +21,9 @@ require 'rainbows/coolio_support'
 #
 # This model is mostly compatible with users of "async.callback" in
 # the Rack environment as long as they do not depend on EventMachine.
+#
+# === RubyGem Requirements
+# * cool.io 1.0.0 or later
 module Rainbows::Coolio
   # :stopdoc:
   # keep-alive timeout scoreboard
@@ -39,10 +42,10 @@ module Rainbows::Coolio
   autoload :ThreadClient, 'rainbows/coolio/thread_client'
   autoload :ResponsePipe, 'rainbows/coolio/response_pipe'
   autoload :ResponseChunkPipe, 'rainbows/coolio/response_chunk_pipe'
+  autoload :Heartbeat, 'rainbows/coolio/heartbeat'
   # :startdoc:
 end
 # :enddoc:
-require 'rainbows/coolio/heartbeat'
 require 'rainbows/coolio/server'
 require 'rainbows/coolio/core'
 Rainbows::Coolio.__send__ :include, Rainbows::Coolio::Core

data/lib/rainbows/coolio/client.rb

@@ -45,7 +45,7 @@ class Rainbows::Coolio::Client < Coolio::IO
   end
 
   def on_readable
-    buf = @_io.kgio_tryread(16384, RBUF)
+    buf = @_io.kgio_tryread(CLIENT_HEADER_BUFFER_SIZE, RBUF)
     case buf
     when :wait_readable
     when nil # eof
@@ -134,7 +134,7 @@ class Rainbows::Coolio::Client < Coolio::IO
       close if @_write_buffer.empty?
     when :headers
       if @buf.empty?
-        buf = @_io.kgio_tryread(16384, RBUF) or return close
+        buf = @_io.kgio_tryread(CLIENT_HEADER_BUFFER_SIZE, RBUF) or return close
         String === buf and return on_read(buf)
         # buf == :wait_readable
         unless enabled?

data/lib/rainbows/coolio/heartbeat.rb

@@ -8,9 +8,10 @@
 class Rainbows::Coolio::Heartbeat < Coolio::TimerWatcher
   KATO = Rainbows::Coolio::KATO
   CONN = Rainbows::Coolio::CONN
+  Rainbows.config!(self, :keepalive_timeout)
 
   def on_timer
-    if (ot = Rainbows.keepalive_timeout) >= 0
+    if (ot = KEEPALIVE_TIMEOUT) >= 0
       ot = Time.now - ot
       KATO.delete_if { |client, time| time < ot and client.timeout? }
     end

data/lib/rainbows/coolio_fiber_spawn.rb

@@ -1,13 +1,17 @@
 # -*- encoding: binary -*-
 require 'rainbows/fiber/coolio'
 
-# A combination of the Coolio and FiberSpawn models.  This allows Ruby
-# 1.9 Fiber-based concurrency for application processing while exposing
-# a synchronous execution model and using scalable network concurrency
-# provided by Cool.io.  A streaming "rack.input" is exposed.
-# Applications are strongly advised to wrap all slow IO objects
-# (sockets, pipes) using the Rainbows::Fiber::IO or a Cool.io-compatible
-# class whenever possible.
+# A combination of the Coolio and FiberSpawn models.
+#
+# This concurrency model is difficult to use with existing applications,
+# lacks third-party support, and is thus NOT recommended.
+#
+# This allows Ruby 1.9 Fiber-based concurrency for application
+# processing while exposing a synchronous execution model and using
+# scalable network concurrency provided by Cool.io.  A streaming
+# "rack.input" is exposed.  Applications are strongly advised to wrap
+# all slow IO objects (sockets, pipes) using the Rainbows::Fiber::IO or
+# a Cool.io-compatible class whenever possible.
 module Rainbows::CoolioFiberSpawn
 
   include Rainbows::Base
@@ -21,6 +25,7 @@ module Rainbows::CoolioFiberSpawn
     Server.const_set(:APP, Rainbows.server.app)
     Heartbeat.new(1, true).attach(Coolio::Loop.default)
     LISTENERS.map! { |s| Server.new(s).attach(Coolio::Loop.default) }
+    Rainbows::Client.__send__ :include, Rainbows::Fiber::Coolio::Methods
     Coolio::Loop.default.run
   end
 end

data/lib/rainbows/coolio_thread_pool.rb

@@ -14,20 +14,29 @@
 #
 # This concurrency model is designed for Ruby 1.9, and Ruby 1.8
 # users are NOT advised to use this due to high CPU usage.
+#
+# === :pool_size vs worker_connections
+#
+# In your Rainbows! config block, you may specify a Thread pool size
+# to limit your application concurrency independently of
+# worker_connections.
+#
+#   Rainbows! do
+#     use :CoolioThreadPool, :pool_size => 50
+#     worker_connections 100
+#   end
+#
+# In extremely rare cases, this may be combined with Rainbows::AppPool
+# if you have different concurrency capabilities for different parts of
+# your Rack application.
+#
+# === RubyGem Requirements
+# * cool.io 1.0.0 or later
 module Rainbows::CoolioThreadPool
   # :stopdoc:
   autoload :Client, 'rainbows/coolio_thread_pool/client'
-  DEFAULTS = {
-    :pool_size => 20, # same default size as ThreadPool (w/o Coolio)
-  }
+  extend Rainbows::PoolSize
   #:startdoc:
-
-  def self.setup # :nodoc:
-    o = Rainbows::O
-    DEFAULTS.each { |k,v| o[k] ||= v }
-    Integer === o[:pool_size] && o[:pool_size] > 0 or
-      raise ArgumentError, "pool_size must a be an Integer > 0"
-  end
   include Rainbows::Coolio::Core
 
   def init_worker_threads(master, queue) # :nodoc:

data/lib/rainbows/coolio_thread_spawn.rb

@@ -13,6 +13,9 @@
 #
 # This concurrency model is designed for Ruby 1.9, and Ruby 1.8
 # users are NOT advised to use this due to high CPU usage.
+#
+# === RubyGem Requirements
+# * cool.io 1.0.0 or later
 module Rainbows::CoolioThreadSpawn
   include Rainbows::Coolio::Core
   autoload :Client, 'rainbows/coolio_thread_spawn/client'

data/lib/rainbows/epoll.rb

@@ -1,11 +1,32 @@
 # -*- encoding: binary -*-
-# :enddoc:
 require 'sleepy_penguin'
 require 'sendfile'
 
-# Edge-triggered epoll concurrency model.  This is extremely unfair
-# and optimized for throughput at the expense of fairness
+# Edge-triggered epoll concurrency model using
+# {sleepy_penguin}[http://bogomips.org/sleepy_penguin/] for epoll.
+#
+# Unlike more portable options like Coolio and EventMachine, this
+# is Linux-only, but uses edge-triggering instead of level-triggering,
+# so it may perform better in some cases.  Coolio and EventMachine have
+# better library support and may be widely-used, however.
+#
+# Consider using XEpoll instead of this if you are using Ruby 1.9,
+# it will avoid accept()-scalability issues with many worker processes.
+#
+# When serving static files, this is extremely unfair and optimized
+# for throughput at the expense of fairness.  This is not an issue
+# if you're not serving static files, or if your working set is
+# small enough to aways be in your kernel page cache.  This concurrency
+# model may starve clients if you have slow disks and large static files.
+#
+# === RubyGem Requirements
+#
+# * raindrops 0.6.0 or later
+# * sleepy_penguin 2.0.0 or later
+# * sendfile 1.1.0 or later
+#
 module Rainbows::Epoll
+  # :stopdoc:
   include Rainbows::Base
   ReRun = []
   autoload :Server, 'rainbows/epoll/server'
@@ -17,9 +38,8 @@ module Rainbows::Epoll
   end
 
   def self.loop
-    timeout = Rainbows.server.timeout
     begin
-      EP.wait(nil, timeout) { |flags, obj| obj.epoll_run }
+      EP.wait(nil, 1000) { |_, obj| obj.epoll_run }
       while obj = ReRun.shift
         obj.epoll_run
       end
@@ -33,6 +53,7 @@ module Rainbows::Epoll
   def init_worker_process(worker)
     super
     Rainbows::Epoll.const_set :EP, SleepyPenguin::Epoll.new
+    Rainbows.at_quit { Rainbows::Epoll::EP.close }
     Rainbows::Client.__send__ :include, Client
   end
 
@@ -40,4 +61,5 @@ module Rainbows::Epoll
     init_worker_process(worker)
     Server.run
   end
+  # :startdoc:
 end