giraffesoft-unicorn 0.93.5

data/SIGNALS

@@ -0,0 +1,97 @@
+== Signal handling
+
+In general, signals need only be sent to the master process.  However,
+the signals Unicorn uses internally to communicate with the worker
+processes are documented here as well.  With the exception of TTIN/TTOU,
+signal handling matches the behavior of {nginx}[http://nginx.net/] so it
+should be possible to easily share process management scripts between
+Unicorn and nginx.
+
+=== Master Process
+
+* HUP - reload config file, app, and gracefully restart all workers
+
+* INT/TERM - quick shutdown, kills all workers immediately
+
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+
+* TTIN - increment the number of worker processes by one
+
+* TTOU - decrement the number of worker processes by one
+
+=== Worker Processes
+
+Sending signals directly to the worker processes should not normally be
+needed.  If the master process is running, any exited worker will be
+automatically respawned.
+
+* INT/TERM - Quick shutdown, immediately exit.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* QUIT - Gracefully exit after finishing the current request.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* 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.
+
+=== Procedure to replace a running unicorn executable
+
+You may replace a running instance of unicorn 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:
+
+1. The path to the unicorn executable script.  If you want to change to
+   a different installation of Ruby, you can modify the shebang
+   line to point to your alternative interpreter.
+
+The procedure is exactly like that of nginx:
+
+1. Send USR2 to the master process
+
+2. Check your process manager or pid files to see if a new master spawned
+   successfully.  If you're using a pid file, the old process will have
+   ".oldbin" appended to its path.  You should have two master instances
+   of unicorn running now, both of which will have workers servicing
+   requests.  Your process tree should look something like this:
+
+     unicorn master (old)
+     \_ unicorn worker[0]
+     \_ unicorn worker[1]
+     \_ unicorn worker[2]
+     \_ unicorn worker[3]
+     \_ unicorn master
+        \_ unicorn worker[0]
+        \_ unicorn worker[1]
+        \_ unicorn worker[2]
+        \_ unicorn worker[3]
+
+3. You can now send WINCH to the old master process so only the new workers
+   serve requests.  If your unicorn process is bound to an interactive
+   terminal, you can skip this step.  Step 5 will be more difficult but
+   you can also skip it if your process is not daemonized.
+
+4. You should now ensure that everything is running correctly with the
+   new workers as the old workers die off.
+
+5. If everything seems ok, then send QUIT to the old master.  You're done!
+
+   If something is broken, then send HUP to the old master to reload
+   the config and restart its workers.  Then send QUIT to the new master
+   process.

data/TODO

@@ -0,0 +1,16 @@
+* Documentation improvements
+
+* ensure test suite passes on non-GNU/Linux systems
+  (likely that it already does)
+
+* consider adding "working_directory" directive to Configurator
+  since START_CTX is ugly...
+
+* consider adding user switching support (ugh...)
+  This makes more sense for Rainbows!, but some folks use it already...
+
+* fix const-correctness in HTTP parser
+
+* performance validation (esp. TeeInput)
+
+* improve test suite (steal from Rainbows!, probably...)

data/TUNING

@@ -0,0 +1,70 @@
+= Tuning Unicorn
+
+Unicorn performance is generally as good as a (mostly) Ruby web server
+can provide.  Most often the performance bottleneck is in the web
+application running on Unicorn rather than Unicorn itself.
+
+== Unicorn Configuration
+
+See Unicorn::Configurator for details on the config file format.
+
+* Setting a very low value for the :backlog parameter in "listen"
+  directives can allow failover to happen more quickly if your
+  cluster is configured for it.
+
+* If you're doing extremely simple benchmarks and getting connection
+  errors under high request rates, increasing your :backlog parameter
+  above the already-generous default of 1024 can help avoid connection
+  errors.  Keep in mind this is not recommended for real traffic if
+  you have another machine to failover to (see above).
+
+* :rcvbuf and :sndbuf parameters generally do not need to be set for TCP
+  listeners under Linux 2.6 because auto-tuning is enabled.  UNIX domain
+  sockets do not have auto-tuning buffer sizes; so increasing those will
+  allow syscalls and task switches to be saved for larger requests
+  and responses.
+
+* Setting "preload_app true" can allow copy-on-write-friendly GC to
+  be used to save memory.  It will probably not work out of the box with
+  applications that open sockets or perform random I/O on files.
+  Databases like TokyoCabinet use concurrency-safe pread()/pwrite()
+  functions for safe sharing of database file descriptors across
+  processes.
+
+* On POSIX-compliant filesystems, it is safe for multiple threads or
+  processes to append to one log file as long as all the processes are
+  have them unbuffered (File#sync = true) or they are
+  record(line)-buffered in userspace.
+
+* worker_processes should be scaled to the number of processes your
+  backend system(s) can support.  DO NOT scale it to the number of
+  external network clients your application expects to be serving.
+  Unicorn is NOT for serving slow clients, that is the job of nginx.
+
+== Kernel Parameters (Linux sysctl)
+
+WARNING: Do not change system parameters unless you know what you're doing!
+
+* net.core.rmem_max and net.core.wmem_max can increase the allowed
+  size of :rcvbuf and :sndbuf respectively. This is mostly only useful
+  for UNIX domain sockets which do not have auto-tuning buffer sizes.
+
+* For load testing/benchmarking with UNIX domain sockets, you should
+  consider increasing net.core.somaxconn or else nginx will start
+  failing to connect under heavy load.  You may also consider setting
+  a higher :backlog to listen on as noted earlier.
+
+* If you're running out of local ports, consider lowering
+  net.ipv4.tcp_fin_timeout to 20-30 (default: 60 seconds).  Also
+  consider widening the usable port range by changing
+  net.ipv4.ip_local_port_range.
+
+* Setting net.ipv4.tcp_timestamps=1 will also allow setting
+  net.ipv4.tcp_tw_reuse=1 and net.ipv4.tcp_tw_recycle=1, which along
+  with the above settings can slow down port exhaustion.  Not all
+  networks are compatible with these settings, check with your friendly
+  network administrator before changing these.
+
+* Increasing the MTU size can reduce framing overhead for larger
+  transfers.  One often-overlooked detail is that the loopback
+  device (usually "lo") can have its MTU increased, too.

data/bin/unicorn

@@ -0,0 +1,165 @@
+#!/home/ew/bin/ruby
+# -*- encoding: binary -*-
+require 'unicorn/launcher'
+require 'optparse'
+
+env = "development"
+daemonize = false
+listeners = []
+options = { :listeners => listeners }
+host, port = Unicorn::Const::DEFAULT_HOST, Unicorn::Const::DEFAULT_PORT
+set_listener = false
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  opts.banner = "Usage: #{File.basename($0)} " \
+                "[ruby options] [unicorn options] [rackup config file]"
+
+  opts.separator "Ruby options:"
+
+  lineno = 1
+  opts.on("-e", "--eval LINE", "evaluate a LINE of code") do |line|
+    eval line, TOPLEVEL_BINDING, "-e", lineno
+    lineno += 1
+  end
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") do
+    $DEBUG = true
+  end
+
+  opts.on("-w", "--warn", "turn warnings on for your script") do
+    $-w = true
+  end
+
+  opts.on("-I", "--include PATH",
+          "specify $LOAD_PATH (may be used more than once)") do |path|
+    $LOAD_PATH.unshift(*path.split(/:/))
+  end
+
+  opts.on("-r", "--require LIBRARY",
+          "require the library, before executing your script") do |library|
+    require library
+  end
+
+  opts.separator "Unicorn options:"
+
+  # some of these switches exist for rackup command-line compatibility,
+
+  opts.on("-o", "--host HOST",
+          "listen on HOST (default: #{Unicorn::Const::DEFAULT_HOST})") do |h|
+    host = h
+    set_listener = true
+  end
+
+  opts.on("-p", "--port PORT",
+          "use PORT (default: #{Unicorn::Const::DEFAULT_PORT})") do |p|
+    port = p.to_i
+    set_listener = true
+  end
+
+  opts.on("-E", "--env ENVIRONMENT",
+          "use ENVIRONMENT for defaults (default: development)") do |e|
+    env = e
+  end
+
+  opts.on("-D", "--daemonize", "run daemonized in the background") do |d|
+    daemonize = d ? true : false
+  end
+
+  opts.on("-P", "--pid FILE", "DEPRECATED") do |f|
+    warn %q{Use of --pid/-P is strongly discouraged}
+    warn %q{Use the 'pid' directive in the Unicorn config file instead}
+    options[:pid] = File.expand_path(f)
+  end
+
+  opts.on("-s", "--server SERVER",
+          "this flag only exists for compatibility") do |s|
+    warn "-s/--server only exists for compatibility with rackup"
+  end
+
+  # Unicorn-specific stuff
+  opts.on("-l", "--listen {HOST:PORT|PATH}",
+          "listen on HOST:PORT or PATH",
+          "this may be specified multiple times",
+          "(default: #{Unicorn::Const::DEFAULT_LISTEN})") do |address|
+    listeners << address
+  end
+
+  opts.on("-c", "--config-file FILE", "Unicorn-specific config file") do |f|
+    options[:config_file] = File.expand_path(f)
+  end
+
+  # I'm avoiding Unicorn-specific config options on the command-line.
+  # IMNSHO, config options on the command-line are redundant given
+  # config files and make things unnecessarily complicated with multiple
+  # places to look for a config option.
+
+  opts.separator "Common options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts.to_s.gsub(/^.*DEPRECATED.*$/s, '')
+    exit
+  end
+
+  opts.on_tail("-v", "--version", "Show version") do
+    puts "unicorn v#{Unicorn::Const::UNICORN_VERSION}"
+    exit
+  end
+
+  opts.parse! ARGV
+end
+
+config = ARGV[0] || "config.ru"
+abort "configuration file #{config} not found" unless File.exist?(config)
+
+if config =~ /\.ru$/
+  # parse embedded command-line options in config.ru comments
+  if File.open(config, "rb") { |fp| fp.sysread(fp.stat.size) } =~ /^#\\(.*)/
+    opts.parse! $1.split(/\s+/)
+  end
+end
+
+require 'pp' if $DEBUG
+
+app = lambda do ||
+  # require Rack as late as possible in case $LOAD_PATH is modified
+  # in config.ru or command-line
+  inner_app = case config
+  when /\.ru$/
+    raw = File.open(config, "rb") { |fp| fp.sysread(fp.stat.size) }
+    raw.sub!(/^__END__\n.*/, '')
+    eval("Rack::Builder.new {(#{raw}\n)}.to_app", nil, config)
+  else
+    require config
+    Object.const_get(File.basename(config, '.rb').capitalize)
+  end
+  pp({ :inner_app => inner_app }) if $DEBUG
+  case env
+  when "development"
+    Rack::Builder.new do
+      use Rack::CommonLogger, $stderr
+      use Rack::ShowExceptions
+      use Rack::Lint
+      run inner_app
+    end.to_app
+  when "deployment"
+    Rack::Builder.new do
+      use Rack::CommonLogger, $stderr
+      run inner_app
+    end.to_app
+  else
+    inner_app
+  end
+end
+
+listeners << "#{host}:#{port}" if set_listener
+
+if $DEBUG
+  pp({
+    :unicorn_options => options,
+    :app => app,
+    :daemonize => daemonize,
+  })
+end
+
+Unicorn::Launcher.daemonize! if daemonize
+Unicorn.run(app, options)

data/bin/unicorn_rails

@@ -0,0 +1,208 @@
+#!/home/ew/bin/ruby
+# -*- encoding: binary -*-
+require 'unicorn/launcher'
+require 'optparse'
+require 'fileutils'
+
+rails_pid = "#{Unicorn::HttpServer::START_CTX[:cwd]}/tmp/pids/unicorn.pid"
+cmd = File.basename($0)
+daemonize = false
+listeners = []
+options = { :listeners => listeners }
+host, port = Unicorn::Const::DEFAULT_HOST, Unicorn::Const::DEFAULT_PORT
+set_listener = false
+ENV['RAILS_ENV'] ||= "development"
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  opts.banner = "Usage: #{cmd} " \
+                "[ruby options] [#{cmd} options] [rackup config file]"
+  opts.separator "Ruby options:"
+
+  lineno = 1
+  opts.on("-e", "--eval LINE", "evaluate a LINE of code") do |line|
+    eval line, TOPLEVEL_BINDING, "-e", lineno
+    lineno += 1
+  end
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") do
+    $DEBUG = true
+  end
+
+  opts.on("-w", "--warn", "turn warnings on for your script") do
+    $-w = true
+  end
+
+  opts.on("-I", "--include PATH",
+          "specify $LOAD_PATH (may be used more than once)") do |path|
+    $LOAD_PATH.unshift(*path.split(/:/))
+  end
+
+  opts.on("-r", "--require LIBRARY",
+          "require the library, before executing your script") do |library|
+    require library
+  end
+
+  opts.separator "#{cmd} options:"
+
+  # some of these switches exist for rackup command-line compatibility,
+
+  opts.on("-o", "--host HOST",
+          "listen on HOST (default: #{Unicorn::Const::DEFAULT_HOST})") do |h|
+    host = h
+    set_listener = true
+  end
+
+  opts.on("-p", "--port PORT", "use PORT (default: #{port})") do |p|
+    port = p.to_i
+    set_listener = true
+  end
+
+  opts.on("-E", "--env RAILS_ENV",
+          "use RAILS_ENV for defaults (default: development)") do |e|
+    ENV['RAILS_ENV'] = e
+  end
+
+  opts.on("-D", "--daemonize", "run daemonized in the background") do |d|
+    daemonize = d ? true : false
+  end
+
+  # Unicorn-specific stuff
+  opts.on("-l", "--listen {HOST:PORT|PATH}",
+          "listen on HOST:PORT or PATH",
+          "this may be specified multiple times",
+          "(default: #{Unicorn::Const::DEFAULT_LISTEN})") do |address|
+    listeners << address
+  end
+
+  opts.on("-c", "--config-file FILE", "Unicorn-specific config file") do |f|
+    options[:config_file] = File.expand_path(f)
+  end
+
+  opts.on("-P PATH", "DEPRECATED") do |v|
+    warn %q{Use of -P is ambiguous and discouraged}
+    warn %q{Use --path or RAILS_RELATIVE_URL_ROOT instead}
+    ENV['RAILS_RELATIVE_URL_ROOT'] = v
+  end
+
+  opts.on("--path PATH", "Runs Rails app mounted at a specific path.",
+          "(default: /)") do |v|
+    ENV['RAILS_RELATIVE_URL_ROOT'] = v
+  end
+
+  # I'm avoiding Unicorn-specific config options on the command-line.
+  # IMNSHO, config options on the command-line are redundant given
+  # config files and make things unnecessarily complicated with multiple
+  # places to look for a config option.
+
+  opts.separator "Common options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts.to_s.gsub(/^.*DEPRECATED.*$/s, '')
+    exit
+  end
+
+  opts.on_tail("-v", "--version", "Show version") do
+    puts " v#{Unicorn::Const::UNICORN_VERSION}"
+    exit
+  end
+
+  opts.parse! ARGV
+end
+
+config = ARGV[0] || (File.exist?('config.ru') ? 'config.ru' : nil)
+
+if config && config =~ /\.ru$/
+  # parse embedded command-line options in config.ru comments
+  if File.open(config, "rb") { |fp| fp.sysread(fp.stat.size) } =~ /^#\\(.*)/
+    opts.parse! $1.split(/\s+/)
+  end
+end
+
+require 'pp' if $DEBUG
+
+# this won't run until after forking if preload_app is false
+app = lambda do ||
+  # Load Rails and the private version of Rack it bundles.
+  begin
+    require 'config/boot'
+  rescue LoadError => err
+    abort "#$0 must be run inside RAILS_ROOT: #{err.inspect}"
+  end
+  defined?(::RAILS_ROOT) or abort "RAILS_ROOT not defined by config/boot"
+  defined?(::RAILS_ENV) or abort "RAILS_ENV not defined by config/boot"
+  defined?(::Rails::VERSION::STRING) or
+    abort "Rails::VERSION::STRING not defined by config/boot"
+
+  inner_app = case config
+  when nil
+    require 'config/environment'
+
+    # it seems Rails >=2.2 support Rack, but only >=2.3 requires it
+    old_rails = case ::Rails::VERSION::MAJOR
+    when 0, 1 then true
+    when 2 then Rails::VERSION::MINOR < 3 ? true : false
+    else
+      false
+    end
+
+    if old_rails
+      require 'unicorn/app/old_rails'
+      Unicorn::App::OldRails.new
+    else
+      ActionController::Dispatcher.new
+    end
+  when /\.ru$/
+    raw = File.open(config, "rb") { |fp| fp.sysread(fp.stat.size) }
+    raw.sub!(/^__END__\n.*/, '')
+    eval("Rack::Builder.new {(#{raw}\n)}.to_app", nil, config)
+  else
+    require config
+    Object.const_get(File.basename(config, '.rb').capitalize)
+  end
+
+  Rack::Builder.new do
+    map_path = ENV['RAILS_RELATIVE_URL_ROOT'] || '/'
+    if inner_app.class.to_s == "Unicorn::App::OldRails"
+      if map_path != '/'
+        # patches + tests welcome, but I really cbf to deal with this
+        # since all apps I've ever dealt with just use "/" ...
+        $stderr.puts "relative URL roots may not work for older Rails"
+      end
+      $stderr.puts "LogTailer not available for Rails < 2.3" unless daemonize
+      $stderr.puts "Debugger not available" if $DEBUG
+      map(map_path) do
+        require 'unicorn/app/old_rails/static'
+        use Unicorn::App::OldRails::Static
+        run inner_app
+      end
+    else
+      use Rails::Rack::LogTailer unless daemonize
+      use Rails::Rack::Debugger if $DEBUG
+      map(map_path) do
+        use Rails::Rack::Static
+        run inner_app
+      end
+    end
+  end.to_app
+end
+
+listeners << "#{host}:#{port}" if set_listener
+
+if $DEBUG
+  pp({
+    :unicorn_options => options,
+    :app => app,
+    :daemonize => daemonize,
+  })
+end
+
+# ensure Rails standard tmp paths exist
+%w(cache pids sessions sockets).each do |dir|
+  FileUtils.mkdir_p("tmp/#{dir}")
+end
+
+if daemonize
+  options[:pid] = rails_pid
+  Unicorn::Launcher.daemonize!
+end
+Unicorn.run(app, options)