rubysl-webrick 1.0.0 → 2.0.0

data/lib/webrick/httpversion.rb

@@ -1,4 +1,4 @@
-#
+#--
 # HTTPVersion.rb -- presentation of HTTP version
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -8,15 +8,33 @@
 # $IPR: httpversion.rb,v 1.5 2002/09/21 12:23:37 gotoyuzo Exp $
 
 module WEBrick
+
+  ##
+  # Represents an HTTP protocol version
+
   class HTTPVersion
     include Comparable
 
-    attr_accessor :major, :minor
+    ##
+    # The major protocol version number
+
+    attr_accessor :major
+
+    ##
+    # The minor protocol version number
+
+    attr_accessor :minor
+
+    ##
+    # Converts +version+ into an HTTPVersion
 
     def self.convert(version)
       version.is_a?(self) ? version : new(version)
     end
 
+    ##
+    # Creates a new HTTPVersion from +version+.
+
     def initialize(version)
       case version
       when HTTPVersion
@@ -32,6 +50,10 @@ module WEBrick
       end
     end
 
+    ##
+    # Compares this version with +other+ according to the HTTP specification
+    # rules.
+
     def <=>(other)
       unless other.is_a?(self.class)
         other = self.class.new(other)
@@ -42,6 +64,10 @@ module WEBrick
       return ret
     end
 
+    ##
+    # The HTTP version as show in the HTTP request and response.  For example,
+    # "1.1"
+
     def to_s
       format("%d.%d", @major, @minor)
     end

data/lib/webrick/log.rb

@@ -1,4 +1,4 @@
-#
+#--
 # log.rb -- Log Class
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -9,12 +9,43 @@
 # $IPR: log.rb,v 1.26 2002/10/06 17:06:10 gotoyuzo Exp $
 
 module WEBrick
+
+  ##
+  # A generic logging class
+
   class BasicLog
-    # log-level constant
-    FATAL, ERROR, WARN, INFO, DEBUG = 1, 2, 3, 4, 5
 
+    # Fatal log level which indicates a server crash
+
+    FATAL = 1
+
+    # Error log level which indicates a recoverable error
+
+    ERROR = 2
+
+    # Warning log level which indicates a possible problem
+
+    WARN  = 3
+
+    # Information log level which indicates possibly useful information
+
+    INFO  = 4
+
+    # Debugging error level for messages used in server development or
+    # debugging
+
+    DEBUG = 5
+
+    # log-level, messages above this level will be logged
     attr_accessor :level
 
+    ##
+    # Initializes a new logger for +log_file+ that outputs messages at +level+
+    # or higher.  +log_file+ can be a filename, an IO-like object that
+    # responds to #<< or nil which outputs to $stderr.
+    #
+    # If no level is given INFO is chosen by default
+
     def initialize(log_file=nil, level=nil)
       @level = level || INFO
       case log_file
@@ -29,11 +60,17 @@ module WEBrick
       end
     end
 
+    ##
+    # Closes the logger (also closes the log device associated to the logger)
     def close
       @log.close if @opened
       @log = nil
     end
 
+    ##
+    # Logs +data+ at +level+ if the given level is above the current log
+    # level.
+
     def log(level, data)
       if @log && level <= @level
         data += "\n" if /\n\Z/ !~ data
@@ -41,26 +78,45 @@ module WEBrick
       end
     end
 
+    ##
+    # Synonym for log(INFO, obj.to_s)
     def <<(obj)
       log(INFO, obj.to_s)
     end
 
+    # Shortcut for logging a FATAL message
     def fatal(msg) log(FATAL, "FATAL " << format(msg)); end
+    # Shortcut for logging an ERROR message
     def error(msg) log(ERROR, "ERROR " << format(msg)); end
+    # Shortcut for logging a WARN message
     def warn(msg)  log(WARN,  "WARN  " << format(msg)); end
+    # Shortcut for logging an INFO message
     def info(msg)  log(INFO,  "INFO  " << format(msg)); end
+    # Shortcut for logging a DEBUG message
     def debug(msg) log(DEBUG, "DEBUG " << format(msg)); end
 
+    # Will the logger output FATAL messages?
     def fatal?; @level >= FATAL; end
+    # Will the logger output ERROR messages?
     def error?; @level >= ERROR; end
+    # Will the logger output WARN messages?
     def warn?;  @level >= WARN; end
+    # Will the logger output INFO messages?
     def info?;  @level >= INFO; end
+    # Will the logger output DEBUG messages?
     def debug?; @level >= DEBUG; end
 
     private
 
+    ##
+    # Formats +arg+ for the logger
+    #
+    # * If +arg+ is an Exception, it will format the error message and
+    #   the back trace.
+    # * If +arg+ responds to #to_str, it will return it.
+    # * Otherwise it will return +arg+.inspect.
     def format(arg)
-      str = if arg.is_a?(Exception)
+      if arg.is_a?(Exception)
         "#{arg.class}: #{arg.message}\n\t" <<
         arg.backtrace.join("\n\t") << "\n"
       elsif arg.respond_to?(:to_str)
@@ -71,14 +127,25 @@ module WEBrick
     end
   end
 
+  ##
+  # A logging class that prepends a timestamp to each message.
+
   class Log < BasicLog
-    attr_accessor :time_format 
+    # Format of the timestamp which is applied to each logged line.  The
+    # default is <tt>"[%Y-%m-%d %H:%M:%S]"</tt>
+    attr_accessor :time_format
 
+    ##
+    # Same as BasicLog#initialize
+    #
+    # You can set the timestamp format through #time_format
     def initialize(log_file=nil, level=nil)
       super(log_file, level)
       @time_format = "[%Y-%m-%d %H:%M:%S]"
     end
 
+    ##
+    # Same as BasicLog#log
     def log(level, data)
       tmp = Time.now.strftime(@time_format)
       tmp << " " << data

data/lib/webrick/server.rb

@@ -10,21 +10,38 @@
 
 require 'thread'
 require 'socket'
-require 'timeout'
 require 'webrick/config'
 require 'webrick/log'
 
 module WEBrick
 
+  ##
+  # Server error exception
+
   class ServerError < StandardError; end
 
+  ##
+  # Base server class
+
   class SimpleServer
+
+    ##
+    # A SimpleServer only yields when you start it
+
     def SimpleServer.start
       yield
     end
   end
 
+  ##
+  # A generic module for daemonizing a process
+
   class Daemon
+
+    ##
+    # Performs the standard operations for daemonizing a process.  Runs a
+    # block, if given.
+
     def Daemon.start
       exit!(0) if fork
       Process::setsid
@@ -38,8 +55,41 @@ module WEBrick
     end
   end
 
+  ##
+  # Base TCP server class.  You must subclass GenericServer and provide a #run
+  # method.
+
   class GenericServer
-    attr_reader :status, :config, :logger, :tokens, :listeners
+
+    ##
+    # The server status.  One of :Stop, :Running or :Shutdown
+
+    attr_reader :status
+
+    ##
+    # The server configuration
+
+    attr_reader :config
+
+    ##
+    # The server logger.  This is independent from the HTTP access log.
+
+    attr_reader :logger
+
+    ##
+    # Tokens control the number of outstanding clients.  The
+    # <code>:MaxClients</code> configuration sets this.
+
+    attr_reader :tokens
+
+    ##
+    # Sockets listening for connections.
+
+    attr_reader :listeners
+
+    ##
+    # Creates a new generic server from +config+.  The default configuration
+    # comes from +default+.
 
     def initialize(config={}, default=Config::General)
       @config = default.dup.update(config)
@@ -67,14 +117,42 @@ module WEBrick
       end
     end
 
+    ##
+    # Retrieves +key+ from the configuration
+
     def [](key)
       @config[key]
     end
 
+    ##
+    # Adds listeners from +address+ and +port+ to the server.  See
+    # WEBrick::Utils::create_listeners for details.
+
     def listen(address, port)
       @listeners += Utils::create_listeners(address, port, @logger)
     end
 
+    ##
+    # Starts the server and runs the +block+ for each connection.  This method
+    # does not return until the server is stopped from a signal handler or
+    # another thread using #stop or #shutdown.
+    #
+    # If the block raises a subclass of StandardError the exception is logged
+    # and ignored.  If an IOError or Errno::EBADF exception is raised the
+    # exception is ignored.  If an Exception subclass is raised the exception
+    # is logged and re-raised which stops the server.
+    #
+    # To completely shut down a server call #shutdown from ensure:
+    #
+    #   server = WEBrick::GenericServer.new
+    #   # or WEBrick::HTTPServer.new
+    #
+    #   begin
+    #     server.start
+    #   ensure
+    #     server.shutdown
+    #   end
+
     def start(&block)
       raise ServerError, "already started." if @status != :Stop
       server_type = @config[:ServerType] || SimpleServer
@@ -86,43 +164,58 @@ module WEBrick
 
         thgroup = ThreadGroup.new
         @status = :Running
-        while @status == :Running
-          begin
-            if svrs = IO.select(@listeners, nil, nil, 2.0)
-              svrs[0].each{|svr|
-                @tokens.pop          # blocks while no token is there.
-                if sock = accept_client(svr)
-                  th = start_thread(sock, &block)
-                  th[:WEBrickThread] = true
-                  thgroup.add(th)
-                else
-                  @tokens.push(nil)
-                end
-              }
+        begin
+          while @status == :Running
+            begin
+              if svrs = IO.select(@listeners, nil, nil, 2.0)
+                svrs[0].each{|svr|
+                  @tokens.pop          # blocks while no token is there.
+                  if sock = accept_client(svr)
+                    sock.do_not_reverse_lookup = config[:DoNotReverseLookup]
+                    th = start_thread(sock, &block)
+                    th[:WEBrickThread] = true
+                    thgroup.add(th)
+                  else
+                    @tokens.push(nil)
+                  end
+                }
+              end
+            rescue Errno::EBADF, IOError => ex
+              # if the listening socket was closed in GenericServer#shutdown,
+              # IO::select raise it.
+            rescue StandardError => ex
+              msg = "#{ex.class}: #{ex.message}\n\t#{ex.backtrace[0]}"
+              @logger.error msg
+            rescue Exception => ex
+              @logger.fatal ex
+              raise
             end
-          rescue Errno::EBADF, IOError => ex
-            # if the listening socket was closed in GenericServer#shutdown,
-            # IO::select raise it.
-          rescue Exception => ex
-            msg = "#{ex.class}: #{ex.message}\n\t#{ex.backtrace[0]}"
-            @logger.error msg
           end
-        end
 
-        @logger.info "going to shutdown ..."
-        thgroup.list.each{|th| th.join if th[:WEBrickThread] }
-        call_callback(:StopCallback)
-        @logger.info "#{self.class}#start done."
-        @status = :Stop
+        ensure
+          @status = :Shutdown
+          @logger.info "going to shutdown ..."
+          thgroup.list.each{|th| th.join if th[:WEBrickThread] }
+          call_callback(:StopCallback)
+          @logger.info "#{self.class}#start done."
+          @status = :Stop
+        end
       }
     end
 
+    ##
+    # Stops the server from accepting new connections.
+
     def stop
       if @status == :Running
         @status = :Shutdown
       end
     end
 
+    ##
+    # Shuts down the server and all listening sockets.  New listeners must be
+    # provided to restart the server.
+
     def shutdown
       stop
       @listeners.each{|s|
@@ -130,17 +223,38 @@ module WEBrick
           addr = s.addr
           @logger.debug("close TCPSocket(#{addr[2]}, #{addr[1]})")
         end
-        s.close
+        begin
+          s.shutdown
+        rescue Errno::ENOTCONN
+          # when `Errno::ENOTCONN: Socket is not connected' on some platforms,
+          # call #close instead of #shutdown.
+          # (ignore @config[:ShutdownSocketWithoutClose])
+          s.close
+        else
+          unless @config[:ShutdownSocketWithoutClose]
+            s.close
+          end
+        end
       }
       @listeners.clear
     end
 
+    ##
+    # You must subclass GenericServer and implement \#run which accepts a TCP
+    # client socket
+
     def run(sock)
       @logger.fatal "run() must be provided by user."
     end
 
     private
 
+    # :stopdoc:
+
+    ##
+    # Accepts a TCP client socket from the TCP server socket +svr+ and returns
+    # the client socket.
+
     def accept_client(svr)
       sock = nil
       begin
@@ -148,16 +262,24 @@ module WEBrick
         sock.sync = true
         Utils::set_non_blocking(sock)
         Utils::set_close_on_exec(sock)
-      rescue Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EPROTO => ex
-        # TCP connection was established but RST segment was sent
-        # from peer before calling TCPServer#accept.
-      rescue Exception => ex
+      rescue Errno::ECONNRESET, Errno::ECONNABORTED,
+             Errno::EPROTO, Errno::EINVAL => ex
+      rescue StandardError => ex
         msg = "#{ex.class}: #{ex.message}\n\t#{ex.backtrace[0]}"
         @logger.error msg
       end
       return sock
     end
 
+    ##
+    # Starts a server thread for the client socket +sock+ that runs the given
+    # +block+.
+    #
+    # Sets the socket to the <code>:WEBrickSocket</code> thread local variable
+    # in the thread.
+    #
+    # If any errors occur in the block they are logged and handled.
+
     def start_thread(sock, &block)
       Thread.start{
         begin
@@ -186,11 +308,14 @@ module WEBrick
           else
             @logger.debug "close: <address unknown>"
           end
-          sock.close
+          sock.close unless sock.closed?
         end
       }
     end
 
+    ##
+    # Calls the callback +callback_name+ from the configuration with +args+
+
     def call_callback(callback_name, *args)
       if cb = @config[callback_name]
         cb.call(*args)