mongrel 1.1.5-x86-mingw32

data/lib/mongrel/cgi.rb

@@ -0,0 +1,181 @@
+# Copyright (c) 2005 Zed A. Shaw 
+# You can redistribute it and/or modify it under the same terms as Ruby.
+#
+# Additional work donated by contributors.  See http://mongrel.rubyforge.org/attributions.html 
+# for more information.
+
+require 'cgi'
+
+module Mongrel
+  # The beginning of a complete wrapper around Mongrel's internal HTTP processing
+  # system but maintaining the original Ruby CGI module.  Use this only as a crutch
+  # to get existing CGI based systems working.  It should handle everything, but please
+  # notify me if you see special warnings.  This work is still very alpha so I need 
+  # testers to help work out the various corner cases.
+  #
+  # The CGIWrapper.handler attribute is normally not set and is available for 
+  # frameworks that need to get back to the handler.  Rails uses this to give
+  # people access to the RailsHandler#files (DirHandler really) so they can
+  # look-up paths and do other things with the files managed there.
+  #
+  # In Rails you can get the real file for a request with:
+  #
+  #  path = @request.cgi.handler.files.can_serve(@request['PATH_INFO'])
+  #
+  # Which is ugly but does the job.  Feel free to write a Rails helper for that.
+  # Refer to DirHandler#can_serve for more information on this.
+  class CGIWrapper < ::CGI
+    public :env_table
+    attr_reader :options
+    attr_accessor :handler
+    # Set this to false if you want calls to CGIWrapper.out to not actually send
+    # the response until you force it.
+    attr_accessor :default_really_final
+
+    # these are stripped out of any keys passed to CGIWrapper.header function
+    REMOVED_KEYS = [ "nph","status","server","connection","type",
+                     "charset","length","language","expires"]
+
+    # Takes an HttpRequest and HttpResponse object, plus any additional arguments
+    # normally passed to CGI.  These are used internally to create a wrapper around
+    # the real CGI while maintaining Mongrel's view of the world.
+    def initialize(request, response, *args)
+      @request = request
+      @response = response
+      @args = *args
+      @input = request.body
+      @head = {}
+      @out_called = false
+      @default_really_final=true
+      super(*args)
+    end
+    
+    # The header is typically called to send back the header.  In our case we
+    # collect it into a hash for later usage.
+    #
+    # nph -- Mostly ignored.  It'll output the date.
+    # connection -- Completely ignored.  Why is CGI doing this?
+    # length -- Ignored since Mongrel figures this out from what you write to output.
+    # 
+    def header(options = "text/html")
+      # if they pass in a string then just write the Content-Type
+      if options.class == String
+        @head['Content-Type'] = options unless @head['Content-Type']
+      else
+        # convert the given options into what Mongrel wants
+        @head['Content-Type'] = options['type'] || "text/html"
+        @head['Content-Type'] += "; charset=" + options['charset'] if options.has_key? "charset" if options['charset']
+        
+        # setup date only if they use nph
+        @head['Date'] = CGI::rfc1123_date(Time.now) if options['nph']
+
+        # setup the server to use the default or what they set
+        @head['Server'] = options['server'] || env_table['SERVER_SOFTWARE']
+
+        # remaining possible options they can give
+        @head['Status'] = options['status'] if options['status']
+        @head['Content-Language'] = options['language'] if options['language']
+        @head['Expires'] = options['expires'] if options['expires']
+
+        # drop the keys we don't want anymore
+        REMOVED_KEYS.each {|k| options.delete(k) }
+
+        # finally just convert the rest raw (which puts 'cookie' directly)
+        # 'cookie' is translated later as we write the header out
+        options.each{|k,v| @head[k] = v}
+      end
+
+      # doing this fakes out the cgi library to think the headers are empty
+      # we then do the real headers in the out function call later
+      ""
+    end
+
+    # Takes any 'cookie' setting and sends it over the Mongrel header,
+    # then removes the setting from the options. If cookie is an 
+    # Array or Hash then it sends those on with .to_s, otherwise
+    # it just calls .to_s on it and hopefully your "cookie" can
+    # write itself correctly.
+    def send_cookies(to)
+      # convert the cookies based on the myriad of possible ways to set a cookie
+      if @head['cookie']
+        cookie = @head['cookie']
+        case cookie
+        when Array
+          cookie.each {|c| to['Set-Cookie'] = c.to_s }
+        when Hash
+          cookie.each_value {|c| to['Set-Cookie'] = c.to_s}
+        else
+          to['Set-Cookie'] = options['cookie'].to_s
+        end
+        
+        @head.delete('cookie')
+      end
+      
+      # @output_cookies seems to never be used, but we'll process it just in case
+      @output_cookies.each {|c| to['Set-Cookie'] = c.to_s } if @output_cookies
+    end
+    
+    # The dumb thing is people can call header or this or both and in any order.
+    # So, we just reuse header and then finalize the HttpResponse the right way.
+    # Status is taken from the various options and converted to what Mongrel needs
+    # via the CGIWrapper.status function.
+    #
+    # We also prevent Rails from actually doing the final send by adding a
+    # second parameter "really_final".  Only Mongrel calls this after Rails
+    # is done.  Since this will break other frameworks, it defaults to 
+    # a different setting for rails (false) and (true) for others.
+    def out(options = "text/html", really_final=@default_really_final)
+      if @out_called || !really_final
+        # don't do it more than once or if it's not the really final call
+        return
+      end
+
+      header(options)
+
+      @response.start status do |head, body|
+        send_cookies(head)
+        
+        @head.each {|k,v| head[k] = v}
+        body.write(yield || "")
+      end
+
+      @out_called = true
+    end
+    
+    # Computes the status once, but lazily so that people who call header twice
+    # don't get penalized.  Because CGI insists on including the options status 
+    # message in the status we have to do a bit of parsing.
+    def status
+      if not @status
+        stat = @head["Status"]
+        stat = stat.split(' ')[0] if stat
+
+        @status = stat || "200"
+      end
+
+      @status
+    end
+
+    # Used to wrap the normal args variable used inside CGI.
+    def args
+      @args
+    end
+    
+    # Used to wrap the normal env_table variable used inside CGI.
+    def env_table
+      @request.params
+    end
+    
+    # Used to wrap the normal stdinput variable used inside CGI.
+    def stdinput
+      @input
+    end
+    
+    # The stdoutput should be completely bypassed but we'll drop a warning just in case
+    def stdoutput
+      STDERR.puts "WARNING: Your program is doing something not expected.  Please tell Zed that stdoutput was used and what software you are running.  Thanks."
+      @response.body
+    end    
+
+  end
+end

data/lib/mongrel/command.rb

@@ -0,0 +1,222 @@
+# Copyright (c) 2005 Zed A. Shaw 
+# You can redistribute it and/or modify it under the same terms as Ruby.
+#
+# Additional work donated by contributors.  See http://mongrel.rubyforge.org/attributions.html 
+# for more information.
+
+require 'singleton'
+require 'optparse'
+
+require 'mongrel/gems'
+Mongrel::Gems.require 'gem_plugin'
+
+module Mongrel
+
+  # Contains all of the various commands that are used with 
+  # Mongrel servers.
+
+  module Command
+
+    BANNER = "Usage: mongrel_rails <command> [options]"
+
+    # A Command pattern implementation used to create the set of command available to the user
+    # from Mongrel.  The script uses objects which implement this interface to do the
+    # user's bidding.
+    module Base
+
+      attr_reader :valid, :done_validating, :original_args
+
+      # Called by the implemented command to set the options for that command.
+      # Every option has a short and long version, a description, a variable to
+      # set, and a default value.  No exceptions.
+      def options(opts)
+        # process the given options array
+        opts.each do |short, long, help, variable, default|
+          self.instance_variable_set(variable, default)
+          @opt.on(short, long, help) do |arg|
+            self.instance_variable_set(variable, arg)
+          end
+        end
+      end
+
+      # Called by the subclass to setup the command and parse the argv arguments.
+      # The call is destructive on argv since it uses the OptionParser#parse! function.
+      def initialize(options={})
+        argv = options[:argv] || []
+        @opt = OptionParser.new
+        @opt.banner = Mongrel::Command::BANNER
+        @valid = true
+        # this is retarded, but it has to be done this way because -h and -v exit
+        @done_validating = false
+        @original_args = argv.dup
+
+        configure
+
+        # I need to add my own -h definition to prevent the -h by default from exiting.
+        @opt.on_tail("-h", "--help", "Show this message") do
+          @done_validating = true
+          puts @opt
+        end
+
+        # I need to add my own -v definition to prevent the -v from exiting by default as well.
+        @opt.on_tail("--version", "Show version") do
+          @done_validating = true
+          if VERSION
+            puts "Version #{Mongrel::Const::MONGREL_VERSION}"
+          end
+        end
+
+        @opt.parse! argv
+      end
+
+      def configure
+        options []
+      end
+
+      # Returns true/false depending on whether the command is configured properly.
+      def validate
+        return @valid
+      end
+
+      # Returns a help message.  Defaults to OptionParser#help which should be good.
+      def help
+        @opt.help
+      end
+
+      # Runs the command doing it's job.  You should implement this otherwise it will
+      # throw a NotImplementedError as a reminder.
+      def run
+        raise NotImplementedError
+      end
+
+
+      # Validates the given expression is true and prints the message if not, exiting.
+      def valid?(exp, message)
+        if not @done_validating and (not exp)
+          failure message
+          @valid = false
+          @done_validating = true
+        end
+      end
+
+      # Validates that a file exists and if not displays the message
+      def valid_exists?(file, message)
+        valid?(file != nil && File.exist?(file), message)
+      end
+
+
+      # Validates that the file is a file and not a directory or something else.
+      def valid_file?(file, message)
+        valid?(file != nil && File.file?(file), message)
+      end
+
+      # Validates that the given directory exists
+      def valid_dir?(file, message)
+        valid?(file != nil && File.directory?(file), message)
+      end
+
+      def valid_user?(user)
+        valid?(@group, "You must also specify a group.")
+        begin
+          Etc.getpwnam(user)
+        rescue
+          failure "User does not exist: #{user}"
+          @valid = false
+        end
+      end
+
+      def valid_group?(group)
+        valid?(@user, "You must also specify a user.")
+        begin
+          Etc.getgrnam(group)
+        rescue
+          failure "Group does not exist: #{group}"
+          @valid = false
+        end
+      end
+
+      # Just a simple method to display failure until something better is developed.
+      def failure(message)
+        STDERR.puts "!!! #{message}"
+      end
+    end
+
+    # A Singleton class that manages all of the available commands
+    # and handles running them.
+    class Registry
+      include Singleton
+
+      # Builds a list of possible commands from the Command derivates list
+      def commands
+        pmgr = GemPlugin::Manager.instance
+        list = pmgr.plugins["/commands"].keys
+        return list.sort
+      end
+
+      # Prints a list of available commands.
+      def print_command_list
+        puts "#{Mongrel::Command::BANNER}\nAvailable commands are:\n\n"
+
+        self.commands.each do |name|
+          if /mongrel::/ =~ name
+            name = name[9 .. -1]
+          end
+
+          puts " - #{name[1 .. -1]}\n"
+        end
+
+        puts "\nEach command takes -h as an option to get help."
+
+      end
+
+
+      # Runs the args against the first argument as the command name.
+      # If it has any errors it returns a false, otherwise it return true.
+      def run(args)
+        # find the command
+        cmd_name = args.shift
+
+        if !cmd_name or cmd_name == "?" or cmd_name == "help"
+          print_command_list
+          return true
+        elsif cmd_name == "--version"
+          puts "Mongrel Web Server #{Mongrel::Const::MONGREL_VERSION}"
+          return true
+        end
+
+        begin
+          # quick hack so that existing commands will keep working but the Mongrel:: ones can be moved
+          if ["start", "stop", "restart"].include? cmd_name
+            cmd_name = "mongrel::" + cmd_name
+          end
+
+          command = GemPlugin::Manager.instance.create("/commands/#{cmd_name}", :argv => args)
+        rescue OptionParser::InvalidOption
+          STDERR.puts "#$! for command '#{cmd_name}'"
+          STDERR.puts "Try #{cmd_name} -h to get help."
+          return false
+        rescue
+          STDERR.puts "ERROR RUNNING '#{cmd_name}': #$!"
+          STDERR.puts "Use help command to get help"
+          return false
+        end
+
+        # Normally the command is NOT valid right after being created
+        # but sometimes (like with -h or -v) there's no further processing
+        # needed so the command is already valid so we can skip it.
+        if not command.done_validating
+          if not command.validate
+            STDERR.puts "#{cmd_name} reported an error. Use mongrel_rails #{cmd_name} -h to get help."
+            return false
+          else
+            command.run
+          end
+        end
+
+        return true
+      end
+
+    end
+  end
+end
+

data/lib/mongrel/configurator.rb

@@ -0,0 +1,388 @@
+require 'yaml'
+require 'etc'
+
+module Mongrel
+  # Implements a simple DSL for configuring a Mongrel server for your 
+  # purposes.  More used by framework implementers to setup Mongrel
+  # how they like, but could be used by regular folks to add more things
+  # to an existing mongrel configuration.
+  #
+  # It is used like this:
+  #
+  #   require 'mongrel'
+  #   config = Mongrel::Configurator.new :host => "127.0.0.1" do
+  #     listener :port => 3000 do
+  #       uri "/app", :handler => Mongrel::DirHandler.new(".", load_mime_map("mime.yaml"))
+  #     end
+  #     run
+  #   end
+  # 
+  # This will setup a simple DirHandler at the current directory and load additional
+  # mime types from mimy.yaml.  The :host => "127.0.0.1" is actually not 
+  # specific to the servers but just a hash of default parameters that all 
+  # server or uri calls receive.
+  #
+  # When you are inside the block after Mongrel::Configurator.new you can simply
+  # call functions that are part of Configurator (like server, uri, daemonize, etc)
+  # without having to refer to anything else.  You can also call these functions on 
+  # the resulting object directly for additional configuration.
+  #
+  # A major thing about Configurator is that it actually lets you configure 
+  # multiple listeners for any hosts and ports you want.  These are kept in a
+  # map config.listeners so you can get to them.
+  #
+  # * :pid_file => Where to write the process ID.
+  class Configurator
+    attr_reader :listeners
+    attr_reader :defaults
+    attr_reader :needs_restart
+
+    # You pass in initial defaults and then a block to continue configuring.
+    def initialize(defaults={}, &block)
+      @listener = nil
+      @listener_name = nil
+      @listeners = {}
+      @defaults = defaults
+      @needs_restart = false
+      @pid_file = defaults[:pid_file]
+
+      if block
+        cloaker(&block).bind(self).call
+      end
+    end
+
+    # Change privileges of the process to specified user and group.
+    def change_privilege(user, group)
+      begin
+        uid, gid = Process.euid, Process.egid
+        target_uid = Etc.getpwnam(user).uid if user
+        target_gid = Etc.getgrnam(group).gid if group
+
+        if uid != target_uid or gid != target_gid
+          log "Initiating groups for #{user.inspect}:#{group.inspect}."
+          Process.initgroups(user, target_gid)
+        
+          log "Changing group to #{group.inspect}."
+          Process::GID.change_privilege(target_gid)
+
+          log "Changing user to #{user.inspect}." 
+          Process::UID.change_privilege(target_uid)
+        end
+      rescue Errno::EPERM => e
+        log "Couldn't change user and group to #{user.inspect}:#{group.inspect}: #{e.to_s}."
+        log "Mongrel failed to start."
+        exit 1
+      end
+    end
+
+    def remove_pid_file
+      File.unlink(@pid_file) if @pid_file and File.exists?(@pid_file)
+    end
+
+    # Writes the PID file if we're not on Windows.
+    def write_pid_file
+      if RUBY_PLATFORM !~ /mswin|mingw/
+        log "Writing PID file to #{@pid_file}"
+        open(@pid_file,"w") {|f| f.write(Process.pid) }
+        open(@pid_file,"w") do |f|
+          f.write(Process.pid)
+          File.chmod(0644, @pid_file)
+        end      
+      end
+    end
+
+    # Generates a class for cloaking the current self and making the DSL nicer.
+    def cloaking_class
+      class << self
+        self
+      end
+    end
+
+    # Do not call this.  You were warned.
+    def cloaker(&block)
+      cloaking_class.class_eval do
+        define_method :cloaker_, &block
+        meth = instance_method( :cloaker_ )
+        remove_method :cloaker_
+        meth
+      end
+    end
+
+    # This will resolve the given options against the defaults.
+    # Normally just used internally.
+    def resolve_defaults(options)
+      options.merge(@defaults)
+    end
+
+    # Starts a listener block.  This is the only one that actually takes
+    # a block and then you make Configurator.uri calls in order to setup
+    # your URIs and handlers.  If you write your Handlers as GemPlugins
+    # then you can use load_plugins and plugin to load them.
+    # 
+    # It expects the following options (or defaults):
+    # 
+    # * :host => Host name to bind.
+    # * :port => Port to bind.
+    # * :num_processors => The maximum number of concurrent threads allowed.
+    # * :throttle => Time to pause (in hundredths of a second) between accepting clients. 
+    # * :timeout => Time to wait (in seconds) before killing a stalled thread.
+    # * :user => User to change to, must have :group as well.
+    # * :group => Group to change to, must have :user as well.
+    #
+    def listener(options={},&block)
+      raise "Cannot call listener inside another listener block." if (@listener or @listener_name)
+      ops = resolve_defaults(options)
+      ops[:num_processors] ||= 950
+      ops[:throttle] ||= 0
+      ops[:timeout] ||= 60
+
+      @listener = Mongrel::HttpServer.new(ops[:host], ops[:port].to_i, ops[:num_processors].to_i, ops[:throttle].to_i, ops[:timeout].to_i)
+      @listener_name = "#{ops[:host]}:#{ops[:port]}"
+      @listeners[@listener_name] = @listener
+
+      if ops[:user] and ops[:group]
+        change_privilege(ops[:user], ops[:group])
+      end
+
+      # Does the actual cloaking operation to give the new implicit self.
+      if block
+        cloaker(&block).bind(self).call
+      end
+
+      # all done processing this listener setup, reset implicit variables
+      @listener = nil
+      @listener_name = nil
+    end
+
+
+    # Called inside a Configurator.listener block in order to 
+    # add URI->handler mappings for that listener.  Use this as
+    # many times as you like.  It expects the following options
+    # or defaults:
+    #
+    # * :handler => HttpHandler -- Handler to use for this location.
+    # * :in_front => true/false -- Rather than appending, it prepends this handler.
+    def uri(location, options={})
+      ops = resolve_defaults(options)
+      @listener.register(location, ops[:handler], ops[:in_front])
+    end
+
+
+    # Daemonizes the current Ruby script turning all the
+    # listeners into an actual "server" or detached process.
+    # You must call this *before* frameworks that open files
+    # as otherwise the files will be closed by this function.
+    #
+    # Does not work for Win32 systems (the call is silently ignored).
+    #
+    # Requires the following options or defaults:
+    #
+    # * :cwd => Directory to change to.
+    # * :log_file => Where to write STDOUT and STDERR.
+    # 
+    # It is safe to call this on win32 as it will only require the daemons
+    # gem/library if NOT win32.
+    def daemonize(options={})
+      ops = resolve_defaults(options)
+      # save this for later since daemonize will hose it
+      if RUBY_PLATFORM !~ /mswin|mingw/
+        require 'daemons/daemonize'
+
+        logfile = ops[:log_file]
+        if logfile[0].chr != "/"
+          logfile = File.join(ops[:cwd],logfile)
+          if not File.exist?(File.dirname(logfile))
+            log "!!! Log file directory not found at full path #{File.dirname(logfile)}.  Update your configuration to use a full path."
+            exit 1
+          end
+        end
+
+        Daemonize.daemonize(logfile)
+
+        # change back to the original starting directory
+        Dir.chdir(ops[:cwd])
+
+      else
+        log "WARNING: Win32 does not support daemon mode."
+      end
+    end
+
+
+    # Uses the GemPlugin system to easily load plugins based on their
+    # gem dependencies.  You pass in either an :includes => [] or 
+    # :excludes => [] setting listing the names of plugins to include
+    # or exclude from the determining the dependencies.
+    def load_plugins(options={})
+      ops = resolve_defaults(options)
+
+      load_settings = {}
+      if ops[:includes]
+        ops[:includes].each do |plugin|
+          load_settings[plugin] = GemPlugin::INCLUDE
+        end
+      end
+
+      if ops[:excludes]
+        ops[:excludes].each do |plugin|
+          load_settings[plugin] = GemPlugin::EXCLUDE
+        end
+      end
+
+      GemPlugin::Manager.instance.load(load_settings)
+    end
+
+
+    # Easy way to load a YAML file and apply default settings.
+    def load_yaml(file, default={})
+      default.merge(YAML.load_file(file))
+    end
+
+
+    # Loads the MIME map file and checks that it is correct
+    # on loading.  This is commonly passed to Mongrel::DirHandler
+    # or any framework handler that uses DirHandler to serve files.
+    # You can also include a set of default MIME types as additional
+    # settings.  See Mongrel::DirHandler for how the MIME types map
+    # is organized.
+    def load_mime_map(file, mime={})
+      # configure any requested mime map
+      mime = load_yaml(file, mime)
+
+      # check all the mime types to make sure they are the right format
+      mime.each {|k,v| log "WARNING: MIME type #{k} must start with '.'" if k.index(".") != 0 }
+
+      return mime
+    end
+
+
+    # Loads and creates a plugin for you based on the given
+    # name and configured with the selected options.  The options
+    # are merged with the defaults prior to passing them in.
+    def plugin(name, options={})
+      ops = resolve_defaults(options)
+      GemPlugin::Manager.instance.create(name, ops)
+    end
+
+    # Lets you do redirects easily as described in Mongrel::RedirectHandler.
+    # You use it inside the configurator like this:
+    #
+    #   redirect("/test", "/to/there") # simple
+    #   redirect("/to", /t/, 'w') # regexp
+    #   redirect("/hey", /(w+)/) {|match| ...}  # block
+    #
+    def redirect(from, pattern, replacement = nil, &block)
+      uri from, :handler => Mongrel::RedirectHandler.new(pattern, replacement, &block)
+    end
+
+    # Works like a meta run method which goes through all the 
+    # configured listeners.  Use the Configurator.join method
+    # to prevent Ruby from exiting until each one is done.
+    def run
+      @listeners.each {|name,s| 
+        s.run 
+      }
+
+      $mongrel_sleeper_thread = Thread.new { loop { sleep 1 } }
+    end
+
+    # Calls .stop on all the configured listeners so they
+    # stop processing requests (gracefully).  By default it
+    # assumes that you don't want to restart.
+    def stop(needs_restart=false, synchronous=false)   
+      @listeners.each do |name,s| 
+        s.stop(synchronous)      
+      end      
+      @needs_restart = needs_restart
+    end
+
+
+    # This method should actually be called *outside* of the
+    # Configurator block so that you can control it.  In other words
+    # do it like:  config.join.
+    def join
+      @listeners.values.each {|s| s.acceptor.join }
+    end
+
+
+    # Calling this before you register your URIs to the given location
+    # will setup a set of handlers that log open files, objects, and the
+    # parameters for each request.  This helps you track common problems
+    # found in Rails applications that are either slow or become unresponsive
+    # after a little while.
+    #
+    # You can pass an extra parameter *what* to indicate what you want to 
+    # debug.  For example, if you just want to dump rails stuff then do:
+    #
+    #   debug "/", what = [:rails]
+    # 
+    # And it will only produce the log/mongrel_debug/rails.log file.
+    # Available options are: :access, :files, :objects, :threads, :rails 
+    # 
+    # NOTE: Use [:files] to get accesses dumped to stderr like with WEBrick.
+    def debug(location, what = [:access, :files, :objects, :threads, :rails])
+      require 'mongrel/debug'
+      handlers = {
+        :access => "/handlers/requestlog::access", 
+        :files => "/handlers/requestlog::files", 
+        :objects => "/handlers/requestlog::objects", 
+        :threads => "/handlers/requestlog::threads",
+        :rails => "/handlers/requestlog::params"
+      }
+
+      # turn on the debugging infrastructure, and ObjectTracker is a pig
+      MongrelDbg.configure
+
+      # now we roll through each requested debug type, turn it on and load that plugin
+      what.each do |type| 
+        MongrelDbg.begin_trace type 
+        uri location, :handler => plugin(handlers[type])
+      end
+    end
+
+    # Used to allow you to let users specify their own configurations
+    # inside your Configurator setup.  You pass it a script name and
+    # it reads it in and does an eval on the contents passing in the right
+    # binding so they can put their own Configurator statements.
+    def run_config(script)
+      open(script) {|f| eval(f.read, proc {self}) }
+    end
+
+    # Sets up the standard signal handlers that are used on most Ruby
+    # It only configures if the platform is not win32 and doesn't do
+    # a HUP signal since this is typically framework specific.
+    #
+    # Requires a :pid_file option given to Configurator.new to indicate a file to delete.  
+    # It sets the MongrelConfig.needs_restart attribute if 
+    # the start command should reload.  It's up to you to detect this
+    # and do whatever is needed for a "restart".
+    #
+    # This command is safely ignored if the platform is win32 (with a warning)
+    def setup_signals(options={})
+      ops = resolve_defaults(options)
+
+      # forced shutdown, even if previously restarted (actually just like TERM but for CTRL-C)
+      trap("INT") { log "INT signal received."; stop(false) }
+
+      # clean up the pid file always
+      at_exit { remove_pid_file }
+
+      if RUBY_PLATFORM !~ /mswin|mingw/
+        # graceful shutdown
+        trap("TERM") { log "TERM signal received."; stop }
+        trap("USR1") { log "USR1 received, toggling $mongrel_debug_client to #{!$mongrel_debug_client}"; $mongrel_debug_client = !$mongrel_debug_client }
+        # restart
+        trap("USR2") { log "USR2 signal received."; stop(true) }
+
+        log "Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart)."
+      else
+        log "Signals ready.  INT => stop (no restart)."
+      end
+    end
+
+    # Logs a simple message to STDERR (or the mongrel log if in daemon mode).
+    def log(msg)
+      STDERR.print "** ", msg, "\n"
+    end
+
+  end
+end