mongrel 0.3.12.4 → 0.3.13

data/ext/http11/http11_parser.h

@@ -1,3 +1,22 @@
+/* Mongrel Web Server - A Mostly Ruby Webserver and Library
+ *
+ * Copyright (C) 2005 Zed A. Shaw zedshaw AT zedshaw dot com
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
 #ifndef http11_parser_h
 #define http11_parser_h
 
@@ -12,11 +31,11 @@ typedef void (*field_cb)(void *data, const char *field, size_t flen, const char
 
 typedef struct http_parser { 
   int cs;
-  const char *body_start;
+  size_t body_start;
   int content_len;
   size_t nread;
-  const char *mark;
-  const char *field_start;
+  size_t mark;
+  size_t field_start;
   size_t field_len;
 
   void *data;
@@ -32,10 +51,9 @@ typedef struct http_parser {
 
 int http_parser_init(http_parser *parser);
 int http_parser_finish(http_parser *parser);
-size_t http_parser_execute(http_parser *parser, const char *data, size_t len );
+size_t http_parser_execute(http_parser *parser, const char *data, size_t len, size_t off);
 int http_parser_has_error(http_parser *parser);
 int http_parser_is_finished(http_parser *parser);
-void http_parser_destroy(http_parser *parser);
 
 #define http_parser_nread(parser) (parser)->nread 
 

data/lib/mongrel.rb

@@ -1,5 +1,24 @@
+# Mongrel Web Server - A Mostly Ruby Webserver and Library
+#
+# Copyright (C) 2005 Zed A. Shaw zedshaw AT zedshaw dot com
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
 require 'socket'
 require 'http11'
+require 'tempfile'
 require 'thread'
 require 'stringio'
 require 'mongrel/cgi'
@@ -8,6 +27,17 @@ require 'mongrel/command'
 require 'mongrel/tcphack'
 require 'yaml'
 require 'time'
+require 'rubygems'
+require 'etc' 
+
+
+begin
+  require 'sendfile'
+  STDERR.puts "** You have sendfile installed, will use that to serve files."
+rescue Object
+  # do nothing
+end
+
 
 # Mongrel module containing all of the classes (include C extensions) for running
 # a Mongrel web server.  It contains a minimalist HTTP server with just enough
@@ -15,6 +45,8 @@ require 'time'
 module Mongrel
 
   class URIClassifier
+    attr_reader :handler_map
+  
     # Returns the URIs that have been registered with this classifier so far.
     # The URIs returned should not be modified as this will cause a memory leak.
     # You can use this to inspect the contents of the URIClassifier.
@@ -77,7 +109,7 @@ module Mongrel
     505  => 'HTTP Version not supported'
   }
 
-  
+
 
   # Frequently used constants when constructing requests or responses.  Many times
   # the constant just refers to a string with the same contents.  Using these constants
@@ -93,13 +125,16 @@ module Mongrel
     # This is the part of the path after the SCRIPT_NAME.  URIClassifier will determine this.
     PATH_INFO="PATH_INFO".freeze
 
-    # This is the intial part that your handler is identified as by URIClassifier.
+    # This is the initial part that your handler is identified as by URIClassifier.
     SCRIPT_NAME="SCRIPT_NAME".freeze
 
     # The original URI requested by the client.  Passed to URIClassifier to build PATH_INFO and SCRIPT_NAME.
     REQUEST_URI='REQUEST_URI'.freeze
 
-    MONGREL_VERSION="0.3.12.4".freeze
+    MONGREL_VERSION="0.3.13".freeze
+
+    # TODO: this use of a base for tempfiles needs to be looked at for security problems
+    MONGREL_TMP_BASE="mongrel".freeze
 
     # The standard empty 404 response for bad requests.  Use Error4040Handler for custom stuff.
     ERROR_404_RESPONSE="HTTP/1.1 404 Not Found\r\nConnection: close\r\nServer: #{MONGREL_VERSION}\r\n\r\nNOT FOUND".freeze
@@ -116,6 +151,9 @@ module Mongrel
     # this, but we'd also like to do this as well.
     MAX_HEADER=1024 * (80 + 32)
 
+    # Maximum request body size before it is moved out of memory and into a tempfile for reading.
+    MAX_BODY=MAX_HEADER
+
     # A frozen format for this is about 15% faster
     STATUS_FORMAT = "HTTP/1.1 %d %s\r\nContent-Length: %d\r\nConnection: close\r\n".freeze
     CONTENT_TYPE = "Content-Type".freeze
@@ -131,6 +169,8 @@ module Mongrel
     LINE_END="\r\n".freeze
     REMOTE_ADDR="REMOTE_ADDR".freeze
     HTTP_X_FORWARDED_FOR="HTTP_X_FORWARDED_FOR".freeze
+    HTTP_IF_UNMODIFIED_SINCE="HTTP_IF_UNMODIFIED_SINCE".freeze
+    HTTP_IF_NONE_MATCH="HTTP_IF_NONE_MATCH".freeze
   end
 
 
@@ -140,30 +180,58 @@ module Mongrel
   # HttpRequest.params Hash that matches common CGI params, and a HttpRequest.body
   # which is a string containing the request body (raw for now).
   #
-  # Mongrel really only supports small-ish request bodies right now since really
-  # huge ones have to be completely read off the wire and put into a string.
-  # Later there will be several options for efficiently handling large file
-  # uploads.
+  # The HttpRequest.initialize method will convert any request that is larger than
+  # Const::MAX_BODY into a Tempfile and use that as the body.  Otherwise it uses 
+  # a StringIO object.  To be safe, you should assume it works like a file.  
   class HttpRequest
     attr_reader :body, :params
 
     # You don't really call this.  It's made for you.
     # Main thing it does is hook up the params, and store any remaining
     # body data into the HttpRequest.body attribute.
+    #
+    # TODO: Implement tempfile removal when the request is done.
     def initialize(params, initial_body, socket)
-      @body = initial_body || ""
       @params = params
       @socket = socket
 
-      # now, if the initial_body isn't long enough for the content length we have to fill it
-      # TODO: adapt for big ass stuff by writing to a temp file
-      clen = params[Const::CONTENT_LENGTH].to_i
-      if @body.length < clen
-        @body << @socket.read(clen - @body.length)
+      clen = params[Const::CONTENT_LENGTH].to_i - initial_body.length
+
+      if clen > Const::MAX_BODY
+        @body = Tempfile.new(Const::MONGREL_TMP_BASE)
+        @body.binmode
+      else
+        @body = StringIO.new
       end
 
+      begin
+        @body.write(initial_body)
+
+        # write the odd sized chunk first
+        clen -= @body.write(@socket.read(clen % Const::CHUNK_SIZE))
+
+        # then stream out nothing but perfectly sized chunks
+        while clen > 0
+          data = @socket.read(Const::CHUNK_SIZE)
+          # have to do it this way since @socket.eof? causes it to block
+          raise "Socket closed or read failure" if not data or data.length != Const::CHUNK_SIZE
+          clen -= @body.write(data)
+          # ASSUME: we are writing to a disk and these writes always write the requested amount
+        end
+
+        # rewind to keep the world happy
+        @body.rewind
+      rescue Object
+        # any errors means we should delete the file, including if the file is dumped
+        STDERR.puts "Error reading request: #$!"
+        @body.delete if @body.class == Tempfile
+        @body = nil # signals that there was a problem
+      end
     end
 
+    # Performs URI escaping so that you can construct proper
+    # query strings faster.  Use this rather than the cgi.rb
+    # version since it's faster.  (Stolen from Camping).
     def self.escape(s)
       s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
         '%'+$1.unpack('H2'*$1.size).join('%').upcase
@@ -171,13 +239,17 @@ module Mongrel
     end
 
 
+    # Unescapes a URI escaped string. (Stolen from Camping).
     def self.unescape(s)
       s.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n){
         [$1.delete('%')].pack('H*')
       } 
     end
 
-
+    # Parses a query string by breaking it up at the '&' 
+    # and ';' characters.  You can also use this to parse
+    # cookies by changing the characters used in the second
+    # parameter (which defaults to '&;'.
     def self.query_parse(qs, d = '&;')
       params = {}
       (qs||'').split(/[#{d}] */n).inject(params) { |h,p|
@@ -195,8 +267,6 @@ module Mongrel
 
       return params
     end
-
-    
   end
 
 
@@ -218,7 +288,6 @@ module Mongrel
     def[]=(key,value)
       @out.write(Const::HEADER_FORMAT % [key, value])
     end
-    
   end
 
   # Writes and controls your response to the client using the HTTP/1.1 specification.
@@ -253,13 +322,14 @@ module Mongrel
   class HttpResponse
     attr_reader :socket
     attr_reader :body
+    attr_writer :body
     attr_reader :header
     attr_reader :status
     attr_writer :status
     attr_reader :body_sent
     attr_reader :header_sent
     attr_reader :status_sent
-    
+
     def initialize(socket)
       @socket = socket
       @body = StringIO.new
@@ -301,8 +371,8 @@ module Mongrel
 
     def send_status(content_length=nil)
       if not @status_sent
-	content_length ||= @body.length
-        @socket.write(Const::STATUS_FORMAT % [status, HTTP_STATUS_CODES[@status], content_length])
+        content_length ||= @body.length
+        write(Const::STATUS_FORMAT % [status, HTTP_STATUS_CODES[@status], content_length])
         @status_sent = true
       end
     end
@@ -310,7 +380,7 @@ module Mongrel
     def send_header
       if not @header_sent
         @header.out.rewind
-        @socket.write(@header.out.read + Const::LINE_END)
+        write(@header.out.read + Const::LINE_END)
         @header_sent = true
       end
     end
@@ -318,14 +388,47 @@ module Mongrel
     def send_body
       if not @body_sent
         @body.rewind
-        # connection: close is also added to ensure that the client does not pipeline.
-        @socket.write(@body.read)
+        write(@body.read)
         @body_sent = true
       end
     end 
 
+    # Appends the contents of +path+ to the response stream.  The file is opened for binary
+    # reading and written in chunks to the socket.  If the 
+    # <a href="http://rubyforge.org/projects/ruby-sendfile">sendfile</a> library is found,
+    # it is used to send the file, often with greater speed and less memory/cpu usage.
+    #
+    # The presence of ruby-sendfile is determined by @socket.response_to? :sendfile, which means
+    # that if you have your own sendfile implementation you can use it without changing this function,
+    # just make sure it follows the ruby-sendfile signature.
+    def send_file(path)
+      File.open(path, "rb") do |f|
+        if @socket.respond_to? :sendfile
+          begin
+            @socket.sendfile(f)
+          rescue => details
+            socket_error(details)
+          end
+        else
+          while chunk = f.read(Const::CHUNK_SIZE) and chunk.length > 0
+            write(chunk)
+          end
+        end
+        @body_send = true
+      end
+    end
+
+    def socket_error(details)
+      # ignore these since it means the client closed off early
+      @socket.close unless @socket.closed?
+      done = true
+      raise details
+    end
+
     def write(data)
       @socket.write(data)
+    rescue => details
+      socket_error(details)
     end
 
     # This takes whatever has been done to header and body and then writes it in the
@@ -336,14 +439,19 @@ module Mongrel
       send_body
     end
 
+    # Used during error conditions to mark the response as "done" so there isn't any more processing
+    # sent to the client.
+    def done=(val)
+      @status_sent = true
+      @header_sent = true
+      @body_sent = true
+    end
+
     def done
       (@status_sent and @header_sent and @body_sent)
     end
 
   end
-  
-
-
 
   # This is the main driver of Mongrel, while the Mognrel::HttpParser and Mongrel::URIClassifier
   # make up the majority of how the server functions.  It's a very simple class that just
@@ -353,7 +461,7 @@ module Mongrel
   # You use it by doing the following:
   #
   #   server = HttpServer.new("0.0.0.0", 3000)
-  #   server.register("/stuff", MyNifterHandler.new)
+  #   server.register("/stuff", MyNiftyHandler.new)
   #   server.run.join
   #
   # The last line can be just server.run if you don't want to join the thread used.
@@ -369,6 +477,8 @@ module Mongrel
     attr_reader :classifier
     attr_reader :host
     attr_reader :port
+    attr_reader :timeout
+    attr_reader :num_processors
 
     # Creates a working server on host:port (strange things happen if port isn't a Number).
     # Use HttpServer::run to start the server and HttpServer.acceptor.join to 
@@ -383,6 +493,8 @@ module Mongrel
     # The timeout parameter is a sleep timeout (in hundredths of a second) that is placed between 
     # socket.accept calls in order to give the server a cheap throttle time.  It defaults to 0 and
     # actually if it is 0 then the sleep is not done at all.
+    #
+    # TODO: Find out if anyone actually uses the timeout option since it seems to cause problems on FBSD.
     def initialize(host, port, num_processors=(2**30-1), timeout=0)
       @socket = TCPServer.new(host, port) 
       @classifier = URIClassifier.new
@@ -393,7 +505,7 @@ module Mongrel
       @num_processors = num_processors
       @death_time = 60
     end
-    
+
 
     # Does the majority of the IO processing.  It has been written in Ruby using
     # about 7 different IO processing strategies and no matter how it's done 
@@ -406,9 +518,14 @@ module Mongrel
         params = {}
 
         data = client.readpartial(Const::CHUNK_SIZE)
+        nparsed = 0
 
-        while true
-          nread = parser.execute(params, data)
+        # Assumption: nparsed will always be less since data will get filled with more
+        # after each parsing.  If it doesn't get more then there was a problem
+        # with the read operation on the client socket.  Effect is to stop processing when the
+        # socket can't fill the buffer for further parsing.
+        while nparsed < data.length
+          nparsed = parser.execute(params, data, nparsed)
 
           if parser.finished?
             script_name, path_info, handlers = @classifier.resolve(params[Const::REQUEST_URI])
@@ -418,44 +535,49 @@ module Mongrel
               params[Const::SCRIPT_NAME] = script_name
               params[Const::REMOTE_ADDR] = params[Const::HTTP_X_FORWARDED_FOR] || client.peeraddr.last
 
-              request = HttpRequest.new(params, data[nread ... data.length], client)
+              # TODO: Find a faster/better way to carve out the range, preferably without copying.
+              request = HttpRequest.new(params, data[nparsed ... data.length] || "", client)
+
+              # in the case of large file uploads the user could close the socket, so skip those requests
+              break if request.body == nil  # nil signals from HttpRequest::initialize that the request was aborted
+
+              # request is good so far, continue processing the response
               response = HttpResponse.new(client)
-              
+
+              # Process each handler in registered order until we run out or one finalizes the response.
               handlers.each do |handler|
                 handler.process(request, response)
-                break if response.done
+                break if response.done or client.closed?
               end
 
-              if not response.done
+              # And finally, if nobody closed the response off, we finalize it.
+              unless response.done or client.closed? 
                 response.finished
               end
-
             else
+              # Didn't find it, return a stock 404 response.
+              # TODO: Implement customer 404 files (but really they should use a real web server).
               client.write(Const::ERROR_404_RESPONSE)
             end
-            
+
             break #done
           else
-            # gotta stream and read again until we can get the parser to be character safe
-            # TODO: make this more efficient since this means we're parsing a lot repeatedly
+            # Parser is not done, queue up more data to read and continue parsing
+            data << client.readpartial(Const::CHUNK_SIZE)
             if data.length >= Const::MAX_HEADER
               raise HttpParserError.new("HEADER is longer than allowed, aborting client early.")
             end
-
-            parser.reset
-            data << client.readpartial(Const::CHUNK_SIZE)
           end
         end
-      rescue EOFError,Errno::ECONNRESET,Errno::EPIPE,Errno::EINVAL
+      rescue EOFError,Errno::ECONNRESET,Errno::EPIPE,Errno::EINVAL,Errno::EBADF
         # ignored
       rescue HttpParserError
-        STDERR.puts "BAD CLIENT (#{client.peeraddr.last}): #$!"
-        STDERR.puts "REQUEST DATA: #{data}"
+        STDERR.puts "#{Time.now}: BAD CLIENT (#{params[Const::HTTP_X_FORWARDED_FOR] || client.peeraddr.last}): #$!"
       rescue => details
-        STDERR.puts "ERROR: #$!"
+        STDERR.puts "#{Time.now}: ERROR: #$!"
         STDERR.puts details.backtrace.join("\n")
       ensure
-        client.close
+        client.close unless client.closed?
       end
     end
 
@@ -473,7 +595,7 @@ module Mongrel
         end
       end
     end
-      
+
 
     # Runs the thing.  It returns the thread used so you can "join" it.  You can also
     # access the HttpServer::acceptor attribute to get the thread later.
@@ -494,15 +616,14 @@ module Mongrel
               thread = Thread.new do
                 process_client(client)
               end
-              
+
               thread[:started_on] = Time.now
               thread.priority=1
               @workers.add(thread)
-              
+
               sleep @timeout/100 if @timeout > 0
             end
           rescue StopServer
-            STDERR.puts "Server stopped.  Exiting."
             @socket.close if not @socket.closed?
             break
           rescue Errno::EMFILE
@@ -511,13 +632,11 @@ module Mongrel
           end
         end
 
-        # now that processing is done we feed enough false onto the request queue to get
-        # each processor to exit and stop processing.
-
-        # finally we wait until the queue is empty (but only about 10 seconds)
+        # troll through the threads that are waiting and kill any that take too long
+        # TODO: Allow for death time to be set if people ask for it.
         @death_time = 10
         shutdown_start = Time.now
-        
+
         while @workers.list.length > 0
           waited_for = (Time.now - shutdown_start).ceil
           STDERR.print "Shutdown waited #{waited_for} for #{@workers.list.length} requests, could take #{@death_time + @timeout} seconds.\r" if @workers.list.length > 0
@@ -529,12 +648,13 @@ module Mongrel
       return @acceptor
     end
 
-    
+
     # Simply registers a handler with the internal URIClassifier.  When the URI is
     # found in the prefix of a request then your handler's HttpHandler::process method
     # is called.  See Mongrel::URIClassifier#register for more information.
     #
     # If you set in_front=true then the passed in handler will be put in front in the list.
+    # Otherwise it's placed at the end of the list.
     def register(uri, handler, in_front=false)
       script_name, path_info, handlers = @classifier.resolve(uri)
 
@@ -551,6 +671,8 @@ module Mongrel
           @classifier.register(uri, [handler])
         end
       end
+
+      handler.listener = self
     end
 
     # Removes any handlers registered at the given URI.  See Mongrel::URIClassifier#unregister
@@ -601,6 +723,8 @@ module Mongrel
   # 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
@@ -608,31 +732,68 @@ module Mongrel
 
     # You pass in initial defaults and then a block to continue configuring.
     def initialize(defaults={}, &blk)
+      @listener = nil
+      @listener_name = nil
       @listeners = {}
       @defaults = defaults
       @needs_restart = false
+      @pid_file = defaults[:pid_file]
+
+      change_privilege(@defaults[:user], @defaults[:group])
       
       if blk
         cloaker(&blk).bind(self).call
       end
     end
     
+    # Change privilege of the process to specified user and group.
+    def change_privilege(user, group)
+      begin
+        if group
+          log "Changing group to #{group}."
+          Process::GID.change_privilege(Etc.getgrnam(group).gid)
+        end
+
+        if user
+          log "Changing user to #{user}." 
+          Process::UID.change_privilege(Etc.getpwnam(user).uid)
+        end
+      rescue Errno::EPERM
+        log "FAILED to change user:group #{user}:#{group}: #$!"
+        exit 1
+      end
+    end
+
+    # Writes the PID file but only if we're on windows.
+    def write_pid_file
+      if RUBY_PLATFORM !~ /mswin/
+        open(@pid_file,"w") {|f| f.write(Process.pid) }
+      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 &blk
-      (class << self; self; end).class_eval do
+    def cloaker(&blk)
+      cloaking_class.class_eval do
         define_method :cloaker_, &blk
         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
@@ -643,9 +804,10 @@ module Mongrel
     # * :host => Host name to bind.
     # * :port => Port to bind.
     # * :num_processors => The maximum number of concurrent threads allowed.  (950 default)
-    # * :timeout => 1/100th of a second timeout between requests. (10 is 1/10th, 0 is not timeout)
+    # * :timeout => 1/100th of a second timeout between requests. (10 is 1/10th, 0 is timeout)
     #
     def listener(options={},&blk)
+      raise "Cannot call listener inside another listener block." if (@listener or @listener_name)
       ops = resolve_defaults(options)
       ops[:num_processors] ||= 950
       ops[:timeout] ||= 0
@@ -653,29 +815,31 @@ module Mongrel
       @listener = Mongrel::HttpServer.new(ops[:host], ops[:port].to_i, ops[:num_processors].to_i, ops[:timeout].to_i)
       @listener_name = "#{ops[:host]}:#{ops[:port]}"
       @listeners[@listener_name] = @listener
-      
+
+      # Does the actual cloaking operation to give the new implicit self.
       if blk
         cloaker(&blk).bind(self).call
       end
-      
-      # all done processing this listener setup
+
+      # 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 => Handler to use for this location.
+    # * :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], in_front=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
@@ -687,35 +851,33 @@ module Mongrel
     #
     # * :cwd => Directory to change to.
     # * :log_file => Where to write STDOUT and STDERR.
-    # * :pid_file => Where to write the process ID.
     # 
-    # It is safe to call this on win32 as it will only require daemons
-    # if NOT win32.
+    # 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/
         require 'daemons/daemonize'
-        
+
         Daemonize.daemonize(log_file=File.join(ops[:cwd], ops[:log_file]))
-        
+
         # change back to the original starting directory
         Dir.chdir(ops[:cwd])
-        
-        open(ops[:pid_file],"w") {|f| f.write(Process.pid) }
+
       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 loading.
+    # or exclude from the when determining the dependencies.
     def load_plugins(options={})
       ops = resolve_defaults(options)
-      
+
       load_settings = {}
       if ops[:includes]
         ops[:includes].each do |plugin|
@@ -731,14 +893,14 @@ module Mongrel
 
       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.
@@ -748,14 +910,14 @@ module Mongrel
     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.
@@ -763,26 +925,32 @@ module Mongrel
       ops = resolve_defaults(options)
       GemPlugin::Manager.instance.create(name, ops)
     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| 
-        log "Running #{name} listener." 
         s.run 
       }
-      
+
+      $mongrel_sleeper_thread = Thread.new { loop { sleep 1 } }
     end
-    
+
     # Calls .stop on all the configured listeners so they
-    # stop processing requests (gracefully).
-    def stop
+    # stop processing requests (gracefully).  By default it
+    # assumes that you don't want to restart and that the pid file
+    # should be unlinked on exit.
+    def stop(needs_restart=false, unlink_pid_file=true)
       @listeners.each {|name,s| 
-        log "Stopping #{name} listener." 
         s.stop 
       }
+
+      @needs_restart = needs_restart
+      if unlink_pid_file
+        File.unlink @pid_file if (@pid_file and File.exist?(@pid_file))
+      end 
     end
 
 
@@ -799,25 +967,32 @@ module Mongrel
     # 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.
-    def debug(location)
+    #
+    # TODO: Document the optional selections from the what parameter
+    def debug(location, what = [:object, :rails, :files, :threads, :params])
       require 'mongrel/debug'
-      ObjectTracker.configure
+      handlers = {
+        :object => "/handlers/requestlog::access", 
+        :rails => "/handlers/requestlog::files", 
+        :files => "/handlers/requestlog::objects", 
+        :threads => "/handlers/requestlog::threads",
+        :params => "/handlers/requestlog::params"
+      }
+
+      # turn on the debugging infrastructure, and ObjectTracker is a pig
+      ObjectTracker.configure if what.include? :object
       MongrelDbg.configure
-      MongrelDbg.begin_trace :objects
-      MongrelDbg.begin_trace :rails
-      MongrelDbg.begin_trace :files
-      MongrelDbg.begin_trace :threads
-      
-      uri location, :handler => plugin("/handlers/requestlog::access")
-      uri location, :handler => plugin("/handlers/requestlog::files")
-      uri location, :handler => plugin("/handlers/requestlog::objects")
-      uri location, :handler => plugin("/handlers/requestlog::params")
-      uri location, :handler => plugin("/handlers/requestlog::threads")
+
+      # 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
-    # reads it in and does an eval on the contents passing in the right
+    # 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}) }
@@ -827,7 +1002,7 @@ module Mongrel
     # 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 to indicate a file to delete.  
+    # 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".
@@ -835,33 +1010,20 @@ module Mongrel
     # 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(need_restart=false) }
+
       if RUBY_PLATFORM !~ /mswin/
         # graceful shutdown
-        trap("TERM") { 
-          log "TERM signal received."
-          stop 
-          File.unlink ops[:pid_file] if File.exist?(ops[:pid_file])
-        }
-        
+        trap("TERM") { log "TERM signal received."; stop }
+
         # restart
-        trap("USR2") { 
-          log "USR2 signal received."
-          stop
-          File.unlink ops[:pid_file] if File.exist?(ops[:pid_file])
-          @needs_restart = true
-        }
-        
-        trap("INT") {
-          log "INT signal received."
-          stop
-          File.unlink ops[:pid_file] if File.exist?(ops[:pid_file])
-          @needs_restart = false
-        }
-        
+        trap("USR2") { log "USR2 signal received."; stop(need_restart=true) }
+
         log "Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart)."
       else
-        log "WARNING: Win32 does not have signals support."
+        log "Signals ready.  INT => stop (no restart)."
       end
     end
 
@@ -869,7 +1031,6 @@ module Mongrel
     def log(msg)
       STDERR.print "** ", msg, "\n"
     end
-    
-  end
 
+  end
 end