scgi 0.6.0

data/COPYING

@@ -0,0 +1,21 @@
+Copyright (c) 2007 Jeremy Evans
+Copyright (c) 2004 Zed A. Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,331 @@
+= ruby-scgi
+
+ruby-scgi is a small Ruby script for running Ruby on Rails (and possibly other
+web applications) for high-speed deployment of your applications in production.
+It is intended as a replacement for the ancient FastCGI code base and bring
+some big advantages to Rails deployment for production operations.  
+
+SCGI (Simple Common Gateway Interface) is a project to replace CGI and FastCGI
+with a simpler protocol to both implement and manage. It was written by Neil
+Schemenauer and adopted by many Python developers as a hosting option.
+   
+ruby-scgi is distributed as a gem, and can be installed with:
+
+    sudo gem install scgi
+
+Feedback/Bugs/Support Requests should be handled through RubyForge at 
+http://rubyforge.org/projects/scgi/.
+
+The RDoc is available at http://code.jeremyevans.net/doc/ruby-scgi/.
+Subversion access is available at svn://code.jeremyevans.net/ruby-scgi/.
+
+== Advantages
+
+* Simultaneous support for Apache1, Apache2, and lighttpd on OSX and most 
+  Linux/BSD systems.
+* Same performance as FastCGI and better performance than other methods.
+* Simple to install, run, and configure.
+* Supports both single-port and multi-port clustering on most systems for that
+  extra boost in concurrency.
+* Supports both command line and config file configuration.
+* Gives out limited status information to help manage your Rails application's
+  resources.
+* Makes it easy to manage your production deployment, and you can even run your
+  application in development mode exactly the same way as with script/server
+  for extra testing efficiency.
+* You can set a maximum concurrent connections limit, which causes any
+  connections over the limit to get redirected to a /busy.html file. This can
+  help keep your site alive under heavy load.
+* Simple to configure with your web server. Even if you use clustering you'll
+  be able to manage your webserver and Rails application independently.
+* Reasonable defaults for almost everything based on user feedback.
+* Completely free code licensed under Rails's own license.
+* No external dependencies other than Ruby
+* The core implementation and the command line tools are easily extensible for
+  other Ruby web frameworks.
+
+== Comparison With FastCGI
+
+SCGI and FastCGI have similar goals:  To keep Ruby running between requests and
+process the requests as fast as possible.  The difference is that SCGI is much
+simpler and easier to implement so there's less chance to get it wrong.
+
+Specifically, ruby-scgi is written in pure Ruby so it doesn't leak memory,
+runs everywhere, and is easy to install (no compilers needed).
+
+One thing that SCGI doesn't support is using UNIX Domain sockets in addition to
+TCP/IP sockets.  This isn't really needed, but it is handy in a shared hosting
+situation where you don't want others connecting to your processes or if you
+have to request open ports.  Sorry, no UNIX Domain sockets in SCGI.
+
+== Comparison With WEBrick
+
+In theory WEBrick should be able to run just as fast as SRR.  They are both
+written in pure Ruby.  They both do similar processing (although WEBrick's are
+a little more complicated).  They both return about the same amount of data.
+
+In practice WEBrick in production mode runs much slower than SRR in production
+mode.  The (dis)advantage (depending on your point of view) is that you have to
+manage your webserver differently than you manage your application.
+
+== Comparison With CGI
+
+CGI is where every time a request comes in for rails the whole Ruby on Rails
+framework is loaded.  This is very slow, but it's easy to install.
+
+An alternative is to use the cgi2scgi program distributed with the SCGI source
+available from http://www.mems-exchange.org/software/scgi/ along with the
+Apache modules.  This program basically is a small little C program that runs
+quickly as a CGI, but passes it's requests to your SRR backend.  It's not all
+that fast, but if you're stuck with cgi-bin only access then this might be just
+the way to go.  Since SCGI runs over TCP/IP you can even host your SRR on a
+totally different machine with this.
+
+== Running and Configuration
+
+If you want to start ruby-scgi with the default configuration, just run:
+
+  scgi_ctrl -d /path/to/rails/app start
+  
+To stop the application:
+
+  scgi_ctrl -d /path/to/rails/app stop
+  
+To restart the application:
+
+  scgi_ctrl -d /path/to/rails/app start # start actually restarts
+  
+Note that restarting/stopping is controlled by a pid file (the location is
+configurable).  If the pidfile exists, it is read and the pids in it are
+killed.  If restarting, new processes are forked after the existing processes
+are killed.
+
+To see the possible and default configuration options, just run the program
+without any arguments:
+
+scgi_ctrl [option=value, ...] (start|stop)
+ Options:
+  -b, --bind          IP address to bind to [127.0.0.1]
+  -c, --config        Location of config file [config/scgi.yaml]
+  -d, --directory     Working directory [.]
+  -e, --environment   Environment (for Rails) [production]
+  -f, --fork          Number of listners on each port [1]
+  -l, --logfile       Location of log file [log/scgi.log]
+  -m, --maxconns      Maximum number of concurrent users [2**30-1]
+  -n, --number        Number of ports to bind to [1]
+  -p, --port          Starting port to bind to [9999]
+  -P, --pidfile       Location of pid file [log/scgi.pid]
+  -r, --processor     Type of processor to use [Rails]
+
+Note that the -d (--directory) option changes the working directory of the
+process, so the -c, -l, and -P options are relative to that.
+
+Here's a longer explanation of the options:
+
+  -b, --bind          IP address to bind to [127.0.0.1]
+  
+  This is the TCP/IP networking sockets to bind to.  It defaults to the
+  loopback address because generally the web application runs on the same
+  physical server as the web server.  If this is not the case, change it to an
+  externally available IP, and make sure to lock down access to the port via a
+  firewall.
+  
+  -c, --config        Location of config file [config/scgi.yaml]
+  
+  This is the configuration file for ruby-scgi.  It is recommended that you use
+  this instead of the command line configuration, as it saves typing.  This
+  path is relative to the working directory, so if it is not inside the working
+  directory, make sure you specify an absolute path.  Also, note that this is
+  the only option that is not configurable from the configuration file.
+  
+  -d, --directory     Working directory [.]
+  
+  This is the working directory of the process.  It should generally be the
+  path to the root of the web application.  Alternatively, you can change to
+  the root of the web application before hand and then not use this option.
+  
+  -e, --environment   Environment (for Rails) [production]
+  
+  This is the only option that is Rails-specific, allowing you to specify the
+  Rails environment on the command line.  It defaults to production because
+  that is the general use case for ruby-scgi.
+  
+  -f, --fork          Number of listners on each port [1]
+  
+  This enables single-port clustering of processes, so there are multiple
+  processes listening on each port.  This can simplify configuration of the
+  webserver, since only a single port need be specified, and can also eliminate
+  the need for a proxy such as pound or pen to handle this for you.  It
+  defaults to one process per port.  Try single port clustering first, and if
+  it is not stable, switch to multiple port clustering.  It is possible to use
+  both as once.
+  
+  -l, --logfile       Location of log file [log/scgi.log]
+  
+  This is the location of the log file, relative to the working directory.
+  ruby-scgi doesn't log all that much (starts, shutdowns, bad requests, other
+  errors, and status info when sent SIGUSR2).
+  
+  -m, --maxconns      Maximum number of concurrent users [2**30-1]
+  
+  The maximum number of concurrent connections.  If more connections that this
+  are sent to the server, it redirects them to the /busy.html file.
+  
+  -n, --number        Number of ports to bind to [1]
+  
+  This enables multi-port clustering.  Multi-port clustering listens on
+  multiple ports starting with the port specified (so port, port+1, port+2,
+  ...).  This makes webserver configuration a little more difficult, and might
+  also require a separate proxy such as pound or pen, so you should try
+  single-port clustering first.  You can run both at once if you want.
+  
+  -p, --port          Starting port to bind to [9999]
+  
+  This is the starting (or only) port that ruby-scgi will use.  If multi-port
+  clustering is used, all ports will be greater than this one.
+  
+  -P, --pidfile       Location of pid file [log/scgi.pid]
+  
+  This is the pid file, relative to the working directory.  The pid file is
+  necessary, as it is what is used to specify which pids to kill when stopping
+  or restarting.  If incorrect information is in the pid file, the processes
+  won't be stopped when they should be, and you will probably won't be able
+  to start new processes (because the ports will still be in use).
+  
+  -r, --processor     Type of processor to use [Rails]
+  
+  This is the type of processor to use, it defaults to Rails, as that is the
+  only one currently supported.  Adding other processers is fairly easy, just
+  make the processor is in a file named XXXXXSCGIProcessor.rb (where XXXXX is
+  in the name of the processor), and that file is located in ruby's library
+  path (the RUBYLIB environment variable).  See RailsSCGIProcessor.rb for an
+  example.
+
+Each of the options can also be specified in the config file as a symbol.  An
+example config file would be:
+
+---
+:port: 4000
+:fork: 3
+
+This sets up a single-port cluster on port 4000 with 3 listening processes.
+
+== Example configurations
+
+Note that ruby-scgi is only tested on Lighttpd.  Also, note that Lighttpd
+1.4.16 has a bug which breaks redirects using server.error-handler-404, so
+either use mod_magnet, wait for 1.4.17, or apply the patch in ticket
+1270 on Lighttpd's Trac.
+
+Lighttpd:
+
+ server.modules = ( ... "mod_scgi" ... )
+ server.error-handler-404 = "/dispatch.scgi"
+ 
+ # For Single Process or Single-Port Clustering
+ scgi.server = ( "dispatch.scgi" => (
+    "server1" => (
+        "host" => "127.0.0.1",
+        "port" => 9999,
+        "check-local" => "disable",
+        "disable-time" => 0)
+    ))
+
+ # For Multi-Port Clustering
+ scgi.server = ( "dispatch.scgi" => (
+    "server1" => (
+        "host" => "127.0.0.1",
+        "port" => 9997,
+        "check-local" => "disable",
+        "disable-time" => 0),
+    "server2" => (
+        "host" => "127.0.0.1",
+        "port" => 9998,
+        "check-local" => "disable",
+        "disable-time" => 0),
+    "server3" => (
+        "host" => "127.0.0.1",
+        "port" => 9999,
+        "check-local" => "disable",
+        "disable-time" => 0)
+    ))
+
+Apache:
+
+ <VirtualHost your-ip:80>
+    AddDefaultCharset utf-8
+    ServerName www.yourdomain
+    DocumentRoot /your-switchtower-root/current/public
+    ErrorDocument 500 /500.html
+    ErrorDocument 404 /404.html
+    # handle all requests throug SCGI
+    SCGIMount / 127.0.0.1:9999
+    # matches locations with a dot following at least one more characters,
+    # that is, things like   *,html, *.css, *.js, which should be delivered
+    # directly from the filesystem
+    <LocationMatch \..+$>
+        # don't handle those with SCGI
+        SCGIHandler Off
+    </LocationMatch>
+    <Directory /your-switchtower-root/current/public/>
+        Options +FollowSymLinks
+        Order allow,deny
+        allow from all
+    </Directory>
+ </VirtualHost>
+
+== Security
+
+Alright, listen up.  I'm not gonna have people trying to take me to court
+because they think I didn't tell them about security problems.  Here are the
+main attack vectors you should be aware of when running this:
+
+* POSIX signals are bad if you're in a shared hosting setup that configures all
+  processes to run as a common user like *nobody*.  If your provider does this
+  then you should use something else or find a better provider.
+* The config file, pid file, and log file and directories should have
+  appropriate permissions. The config file should ideally be readable but not
+  writable by the user running scgi_ctrl.  The pid and log file directory
+  should be writable by the user running scgi_ctrl and by no other user.  If
+  the config file is writable by a non-trusted user, they could potentially
+  run arbitrary code, and they could certainly open arbitrary ports and or
+  attempt denial of service.  If the pid file is writable by a non-trusted
+  user, it could cause arbitrary processes to be killed by the user running
+  scgi_ctrl
+* Never run scgi_ctrl as root.  If you don't know why you should read up about
+  the unix security model before deploying any more software.
+
+== Changes from previous versions
+
+* Single-port clustering is back
+* scgi_ctrl is fully configurable on the command line
+* Clustering and processing are now built into scgi_ctrl
+* DRb, Win32, and throttling are no longer supported
+* Soft reconfiguration is no longer supported (no SIGUSR1)
+* Restarting via SIGHUP is no longer supported (SIGHUP is the same as SIGINT)
+* The only commands available to scgi_ctrl are start and stop
+
+== FAQ
+
+Q: Have you been living under a rock for the last two years?  Mongrel/Nginx is
+the new hotness!
+
+A: Well, aren't you snotty.  You can certainly use Mongrel if you want.  The
+memory/performance differences are small, and it is probably better maintained.
+ruby-scgi may have simpler clustering, and may be useful for certain legacy
+setups.  Also, it works well and it's been working for me for the last few
+years, so I haven't felt the need to change.
+
+Q: Does it work with Capistrano yet?
+
+A: I haven't tried.  If you have luck, let me know.
+
+Q: Is there an easy way to reload?  I don't want to take the whole thing down
+just to deploy new code.
+
+A: scgi_ctrl always uses SIGINT to stop processes, which allows existing
+clients to finish.  Restarting may have problems if a lot of clients are
+connected and the processes can't shutdown before the new listening socket is
+bound.  This hasn't been a problem for me yet, but it is a possible race
+condition.  In case it affects you, you may have to run scgi_ctrl start again
+if you get an error binding to a port.

data/bin/scgi_ctrl

@@ -0,0 +1,132 @@
+#!/usr/local/bin/ruby
+require 'getoptlong'
+require 'yaml'
+SCGI_DEFAULT_CONFIG = {:pidfile=>'log/scgi.pid', :number=>1, :port=>9999,
+  :processor=>'Rails', :fork=>1, :logfile=>'log/scgi.log', :maxconns=>2**30-1,
+  :bind=>'127.0.0.1', :command=>''}
+SCGI_CONFIG = {}
+
+def config_file_options(filename)
+  begin
+    config = YAML.load(File.read(filename))
+    config.is_a?(Hash) ? config : Hash.new
+  rescue
+    Hash.new
+  end
+end
+
+def get_processor(string)
+  raise NameError, "#{string} is not a valid processor!" unless string =~ /\A[A-Z][A-ZA-z]*\z/
+  processor = "#{string}SCGIProcessor"
+  require processor
+  eval(processor)
+end
+
+def parse_options
+  config = {:config => 'config/scgi.yaml'}
+  opts = GetoptLong.new(
+    [ '--bind', '-b', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--config', '-c', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--directory', '-d', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--environment', '-e', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--fork', '-f', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--logfile', '-l', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--maxconns', '-m', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--number', '-n', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--port', '-p', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--pidfile', '-P', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--processor', '-r', GetoptLong::REQUIRED_ARGUMENT ]
+  )
+  opts.each do |opt, arg|
+    case opt
+      when '--bind'
+        config[:bind] = arg
+      when '--config'
+        config[:config] = arg
+      when '--directory'
+        Dir.chdir(arg)
+      when '--environment'
+        config[:environment] = arg
+      when '--fork'
+        config[:fork] = arg.to_i
+      when '--logfile'
+        config[:logile] = arg
+      when '--maxconns'
+        config[:maxconns] = arg.to_i
+      when '--number'
+        config[:number] = arg.to_i
+      when '--port'
+        config[:port] = arg.to_i
+      when '--pidfile'
+        config[:pidfile] = arg
+      when '--processor'
+        config[:processor] = arg
+    end
+  end
+  
+  # Configuration Precedence: Command Line > Config File > Default
+  SCGI_CONFIG.merge!(SCGI_DEFAULT_CONFIG)
+  SCGI_CONFIG.merge!(config_file_options(config[:config]))
+  SCGI_CONFIG.merge!(config)
+end
+
+def process(command)
+  case command
+    when 'start'
+      stop
+      start
+    when 'stop'
+      stop
+    else
+      puts usage
+  end
+end
+
+def start
+  processor = get_processor(SCGI_CONFIG[:processor]).new(SCGI_CONFIG)
+  pids = []
+  SCGI_CONFIG[:number].times do |i|
+    socket = TCPServer.new(SCGI_CONFIG[:bind], port = SCGI_CONFIG[:port]+i)
+    SCGI_CONFIG[:fork].times do
+      if pid = fork
+        pids << pid
+      else
+        $0 = "scgi-#{SCGI_CONFIG[:processor]} dir:#{Dir.pwd} port:#{port}"
+        return processor.listen(socket)
+      end
+    end
+  end
+  File.open(SCGI_CONFIG[:pidfile], 'wb'){|file| file.print("#{pids.join(' ')}")}
+end
+
+def stop
+  if File.file?(SCGI_CONFIG[:pidfile])
+    pids = nil
+    File.open(SCGI_CONFIG[:pidfile], 'rb'){|f| pids = f.read.split.collect{|x| x.to_i if x.to_i > 0}.compact}
+    if pids.length > 0
+      Process.kill("INT", *pids) rescue return nil
+      File.delete(SCGI_CONFIG[:pidfile])
+    end
+  end
+end
+
+def usage
+  <<-END
+scgi_ctrl [option=value, ...] (start|stop)
+ Options:
+  -b, --bind          IP address to bind to [127.0.0.1]
+  -c, --config        Location of config file [config/scgi.yaml]
+  -d, --directory     Working directory [.]
+  -e, --environment   Environment (for Rails) [production]
+  -f, --fork          Number of listners on each port [1]
+  -l, --logfile       Location of log file [log/scgi.log]
+  -m, --maxconns      Maximum number of concurrent users [2**30-1]
+  -n, --number        Number of ports to bind to [1]
+  -p, --port          Starting port to bind to [9999]
+  -P, --pidfile       Location of pid file [log/scgi.pid]
+  -r, --processor     Type of processor to use [Rails]
+END
+end
+
+parse_options
+process(ARGV[0])

data/lib/RailsSCGIProcessor.rb

@@ -0,0 +1,28 @@
+#!/usr/local/bin/ruby
+require 'scgi'
+
+# This SCGI::Processor subclass hooks the SCGI request into Ruby on Rails.
+class RailsSCGIProcessor < SCGI::Processor 
+  # Initialzes Rails with the appropriate environment and settings
+  def initialize(settings)
+    ENV["RAILS_ENV"] = settings[:environment] || 'production'
+    require "config/environment"
+    ActiveRecord::Base.threaded_connections = false
+    require 'dispatcher'
+    super(settings)
+    @guard = Mutex.new
+  end
+  
+  # Submits requests to Rails in a single threaded fashion
+  def process_request(request, body, socket)
+    return if socket.closed?
+    cgi = SCGI::CGIFixed.new(request, body, socket)
+    begin
+      @guard.synchronize{Dispatcher.dispatch(cgi, ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS, cgi.stdoutput)}
+    rescue IOError
+      @log.error("received IOError #$! when handling client.  Your web server doesn't like me.")
+    rescue Object => rails_error
+      @log.error("calling Dispatcher.dispatch", rails_error)
+    end
+  end
+end

data/lib/scgi.rb

@@ -0,0 +1,272 @@
+#!/usr/local/bin/ruby
+
+require 'stringio'
+require 'socket'
+require 'cgi'
+require 'monitor'
+require 'singleton'
+
+module SCGI
+  # A factory that makes Log objects, making sure that one Log is associated
+  # with each log file.
+  class LogFactory < Monitor
+    include Singleton
+    
+    def initialize
+      super()
+      @@logs = {}
+    end
+      
+    def create(file)
+      synchronize{@@logs[file] ||= Log.new(file)}
+    end
+  end
+    
+  # A simple Log class that has an info and error method for output
+  # messages to a log file.  The main thing this logger does is 
+  # include the process ID in the logs so that you can see which child
+  # is creating each message.
+  class Log < Monitor
+    def initialize(file)
+      super()
+      @out = open(file, "a+")
+      @out.sync = true
+      @pid = Process.pid
+      @info = "[INF][#{@pid}] "
+      @error = "[ERR][#{@pid}] "
+    end
+    
+    def info(msg)
+      synchronize{@out.print("#{@info}#{msg}\n")}
+    end
+    
+    # If an exception is given then it will print the exception and a stack trace.
+    def error(msg, exc=nil)
+      return synchronize{@out.print("#{@error}#{msg}\n")} unless exc
+      synchronize{@out.print("#{@error}#{msg}: #{exc}\n#{exc.backtrace.join("\n")}\n")}
+    end
+  end
+
+  # Modifies CGI so that we can use it.  Main thing it does is expose
+  # the stdinput and stdoutput so SCGI::Processor can connect them to
+  # the right sources.  It also exposes the env_table so that SCGI::Processor
+  # and hook the SCGI parameters into the environment table.
+  class CGIFixed < ::CGI
+    public :env_table
+    attr_reader :args, :env_table
+
+    def initialize(params, data, out, *args)
+      @env_table = params
+      @args = *args
+      @input = StringIO.new(data)
+      @out = out
+      super(*args)
+    end
+    
+    def stdinput
+      @input
+    end
+    
+    def stdoutput
+      @out
+    end
+  end
+
+  # This is the complete guts of the SCGI system.  It is designed so that
+  # people can take it and implement it for their own systems, not just 
+  # Ruby on Rails.  This implementation is not complete since you must
+  # create your own that implements the process_request method.
+  #
+  # The SCGI protocol only works with TCP/IP sockets and not domain sockets.
+  # It might be useful for shared hosting people to have domain sockets, but
+  # they aren't supported in Apache, and in lighttpd they're unreliable.
+  # Also, domain sockets don't work so well on Windows.
+  class Processor < Monitor
+    attr_reader :settings
+    
+    def initialize(settings = {})
+      @total_conns = 0
+      @shutdown = false
+      @dead = false
+      @threads = Queue.new
+      @settings = settings
+      @log = LogFactory.instance.create(settings[:logfile])
+      @host = settings[:bind]
+      @port = settings[:port]
+      @maxconns = settings[:maxconns]
+      super()
+      setup_signals
+    end
+        
+    # Starts the SCGI::Processor having it listen on either the
+    # given socket or listening to a new socket on the @host/@port
+    # configured.  The option to give listen a socket is there so
+    # that others can create one socket, and then fork several processors
+    # to listen to it.
+    #
+    # This function does not return until a shutdown.
+    def listen(socket = nil)
+      @log.info("Started listening on #{@host}:#{@port} at #{@started = Time.now}")
+      @socket = socket || TCPServer.new(@host, @port)
+      
+      # we also need a small collector thread that does nothing
+      # but pull threads off the thread queue and joins them
+      @collector = Thread.new do
+        while t = @threads.shift
+          collect_thread(t)
+          @total_conns += 1
+        end
+      end
+        
+      thread = Thread.new do
+        loop do
+          handle_client(@socket.accept)
+          break if @shutdown and @threads.length <= 0
+        end
+      end
+        
+      # and then collect the listener thread which blocks until it exits
+      collect_thread(thread)
+      
+      @socket.close unless @socket.closed?
+      @dead = true
+      @log.info("Exited accept loop. Shutdown complete.")
+    end
+    
+    def collect_thread(thread)
+      begin
+        thread.join
+      rescue Interrupt
+        @log.info("Shutting down from SIGINT.")
+      rescue IOError
+        @log.error("received IOError #$!.  Web server may possibly be configured wrong.")
+      rescue Object
+        @log.error("Collecting thread", $!)
+      end
+    end
+    
+    # Internal function that handles a new client connection.
+    # It spawns a thread to handle the client and registers it in the 
+    # @threads queue.  A collector thread is responsible for joining these
+    # and clearing them out.  This design is needed because Ruby's GC
+    # doesn't seem to deal with threads as well as others believe.
+    #
+    # Depending on how your system works, you may need to synchronize 
+    # inside your process_request implementation.  scgi_rails.rb
+    # does this so that Rails will run as if it were single threaded.
+    #
+    # It also handles calculating the current and total connections,
+    # and deals with the graceful shutdown.  The important part 
+    # of graceful shutdown is that new requests get redirected to
+    # the /busy.html file.
+    #
+    def handle_client(socket)
+      # ruby's GC seems to do weird things if we don't assign the thread to a local variable
+      @threads << Thread.new do
+        begin
+          len = ""
+          # we only read 10 bytes of the length.  any request longer than this is invalid
+          while len.length <= 10
+            c = socket.read(1)
+            break if c == ':' # found the terminal, len now has a length in it so read the payload
+            len << c
+          end
+          
+          # we should now either have a payload length to get
+          payload = socket.read(len.to_i)
+          if socket.read(1) == ','
+            read_header(socket, payload)
+          else
+            @log.error("Malformed request, does not end with ','")
+          end
+        rescue Object
+          @log.error("Handling client", $!)
+        ensure
+          # no matter what we have to put this thread on the bad list
+          socket.close if not socket.closed?
+        end
+      end
+    end
+    
+    # Does three jobs:  reads and parses the SCGI netstring header,
+    # reads any content off the socket, and then either calls process_request
+    # or immediately returns a redirect to /busy.html for some connections.
+    #
+    # The browser/connection that will be redirected to /busy.html if 
+    # either SCGI::Processor is in the middle of a shutdown, or if the
+    # number of connections is over the @maxconns.  This redirect is
+    # immediate and doesn't run inside the interpreter, so it will happen with
+    # much less processing and help keep your system responsive.
+    def read_header(socket, payload)
+      return if socket.closed?
+      request = Hash[*(payload.split("\0"))]
+      if request["CONTENT_LENGTH"]
+        length = request["CONTENT_LENGTH"].to_i
+        body = length > 0 ? socket.read(length) : ''
+        
+        if @shutdown or @threads.length > @maxconns
+          socket.write("Location: /busy.html\r\nCache-control: no-cache, must-revalidate\r\nExpires: Mon, 26 Jul 1997 05:00:00 GMT\r\nStatus: 307 Temporary Redirect\r\n\r\n")
+        else
+          process_request(request, body, socket)
+        end
+      end
+    end
+    
+    # You must implement this yourself.  The request is a Hash
+    # of the CGI parameters from the webserver.  The body is the
+    # raw CGI body.  The socket is where you write your results
+    # (properly HTTP formatted) back to the webserver.
+    def process_request(request, body, socket)
+      raise "You must implement process_request"
+    end
+    
+    # Sets up the POSIX signals:
+    #
+    # * TERM -- Forced shutdown.
+    # * INT -- Graceful shutdown.
+    # * HUP -- Graceful shutdown.
+    # * USR2 -- Dumps status info to the logs.  Super ugly.
+    def setup_signals
+      trap("TERM") { @log.info("SIGTERM, forced shutdown."); shutdown(force=true) }
+      trap("INT") { @log.info("SIGINT, graceful shutdown started."); shutdown }
+      trap("HUP") { @log.info("SIGHUP, graceful shutdown started."); shutdown }
+      trap("USR2") { @log.info(status_info) }
+    end
+        
+    # Returns a Hash with status information.  This is used
+    # when dumping data to the logs
+    def status_info
+      { 
+      :time => Time.now,  :pid => Process.pid, :settings => @settings,
+      :environment => @settings[:environment], :started => @started,
+      :max_conns => @maxconns, :conns => @threads.length, :systimes => Process.times,
+      :shutdown => @shutdown, :dead => @dead, :total_conns => @total_conns
+      }.inspect
+    end
+        
+    # When called it will set the @shutdown flag indicating to the 
+    # SCGI::Processor.listen function that all new connections should
+    # be set to /busy.html, and all current connections should be 
+    # "valved" off.  Once all the current connections are gone the
+    # SCGI::Processor.listen function will exit.
+    #
+    # Use the force=true parameter to force an immediate shutdown.
+    # This is done by closing the listening socket, so it's rather
+    # violent.
+    def shutdown(force = false)
+      synchronize do
+        @shutdown = true
+        
+        if @threads.length == 0 
+          @log.info("Immediate shutdown since nobody is connected.")
+          @socket.close
+        elsif force
+          @log.info("Forcing shutdown.  You may see exceptions.")
+          @socket.close
+        else
+          @log.info("Shutdown requested.  Beginning graceful shutdown with #{@threads.length} connected.")
+        end
+      end
+    end        
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: scgi
+version: !ruby/object:Gem::Version 
+  version: 0.6.0
+date: 2007-08-13 00:00:00 -07:00
+summary: Simple support for using SCGI in ruby apps, such as Rails
+require_paths: 
+- lib
+email: code@jeremyevans.net
+homepage: 
+rubyforge_project: 
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Jeremy Evans
+files: 
+- COPYING
+- README
+- lib/scgi.rb
+- lib/RailsSCGIProcessor.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- scgi_ctrl
+extensions: []
+
+requirements: []
+
+dependencies: []
+