rubysl-webrick 1.0.0 → 2.0.0

data/lib/webrick/httpresponse.rb

@@ -15,21 +15,85 @@ require 'webrick/httputils'
 require 'webrick/httpstatus'
 
 module WEBrick
+  ##
+  # An HTTP response.  This is filled in by the service or do_* methods of a
+  # WEBrick HTTP Servlet.
+
   class HTTPResponse
-    BUFSIZE = 1024*4
 
-    attr_reader :http_version, :status, :header
+    ##
+    # HTTP Response version
+
+    attr_reader :http_version
+
+    ##
+    # Response status code (200)
+
+    attr_reader :status
+
+    ##
+    # Response header
+
+    attr_reader :header
+
+    ##
+    # Response cookies
+
     attr_reader :cookies
+
+    ##
+    # Response reason phrase ("OK")
+
     attr_accessor :reason_phrase
+
+    ##
+    # Body may be a String or IO subclass.
+
     attr_accessor :body
 
-    attr_accessor :request_method, :request_uri, :request_http_version
+    ##
+    # Request method for this response
+
+    attr_accessor :request_method
+
+    ##
+    # Request URI for this response
+
+    attr_accessor :request_uri
+
+    ##
+    # Request HTTP version for this response
+
+    attr_accessor :request_http_version
+
+    ##
+    # Filename of the static file in this response.  Only used by the
+    # FileHandler servlet.
+
     attr_accessor :filename
+
+    ##
+    # Is this a keep-alive response?
+
     attr_accessor :keep_alive
-    attr_reader :config, :sent_size
+
+    ##
+    # Configuration for this response
+
+    attr_reader :config
+
+    ##
+    # Bytes sent in this response
+
+    attr_reader :sent_size
+
+    ##
+    # Creates a new HTTP response object.  WEBrick::Config::HTTP is the
+    # default configuration.
 
     def initialize(config)
       @config = config
+      @buffer_size = config[:OutputBufferSize]
       @logger = config[:Logger]
       @header = Hash.new
       @status = HTTPStatus::RC_OK
@@ -46,58 +110,97 @@ module WEBrick
       @sent_size = 0
     end
 
+    ##
+    # The response's HTTP status line
+
     def status_line
       "HTTP/#@http_version #@status #@reason_phrase #{CRLF}"
     end
 
+    ##
+    # Sets the response's status to the +status+ code
+
     def status=(status)
       @status = status
       @reason_phrase = HTTPStatus::reason_phrase(status)
     end
 
+    ##
+    # Retrieves the response header +field+
+
     def [](field)
       @header[field.downcase]
     end
 
+    ##
+    # Sets the response header +field+ to +value+
+
     def []=(field, value)
       @header[field.downcase] = value.to_s
     end
 
+    ##
+    # The content-length header
+
     def content_length
       if len = self['content-length']
         return Integer(len)
       end
     end
 
+    ##
+    # Sets the content-length header to +len+
+
     def content_length=(len)
       self['content-length'] = len.to_s
     end
 
+    ##
+    # The content-type header
+
     def content_type
       self['content-type']
     end
 
+    ##
+    # Sets the content-type header to +type+
+
     def content_type=(type)
       self['content-type'] = type
     end
 
+    ##
+    # Iterates over each header in the resopnse
+
     def each
-      @header.each{|k, v|  yield(k, v) }
+      @header.each{|field, value|  yield(field, value) }
     end
 
+    ##
+    # Will this response body be returned using chunked transfer-encoding?
+
     def chunked?
       @chunked
     end
 
+    ##
+    # Enables chunked transfer encoding.
+
     def chunked=(val)
       @chunked = val ? true : false
     end
 
+    ##
+    # Will this response's connection be kept alive?
+
     def keep_alive?
       @keep_alive
     end
 
-    def send_response(socket)
+    ##
+    # Sends the response on +socket+
+
+    def send_response(socket) # :nodoc:
       begin
         setup_header()
         send_header(socket)
@@ -111,7 +214,10 @@ module WEBrick
       end
     end
 
-    def setup_header()
+    ##
+    # Sets up the headers for sending
+
+    def setup_header() # :nodoc:
       @reason_phrase    ||= HTTPStatus::reason_phrase(@status)
       @header['server'] ||= @config[:ServerSoftware]
       @header['date']   ||= Time.now.httpdate
@@ -143,7 +249,7 @@ module WEBrick
         @header.delete('content-length')
       elsif @header['content-length'].nil?
         unless @body.is_a?(IO)
-          @header['content-length'] = @body ? @body.size : 0
+          @header['content-length'] = @body ? @body.bytesize : 0
         end
       end
 
@@ -151,8 +257,13 @@ module WEBrick
       if @header['connection'] == "close"
          @keep_alive = false
       elsif keep_alive?
-        if chunked? || @header['content-length']
+        if chunked? || @header['content-length'] || @status == 304 || @status == 204 || HTTPStatus.info?(@status)
           @header['connection'] = "Keep-Alive"
+        else
+          msg = "Could not determine content-length of response body. Set content-length of the response or set Response#chunked = true"
+          @logger.warn(msg)
+          @header['connection'] = "close"
+          @keep_alive = false
         end
       else
         @header['connection'] = "close"
@@ -166,11 +277,14 @@ module WEBrick
       end
     end
 
-    def send_header(socket)
+    ##
+    # Sends the headers on +socket+
+
+    def send_header(socket) # :nodoc:
       if @http_version.major > 0
         data = status_line()
         @header.each{|key, value|
-          tmp = key.gsub(/\bwww|^te$|\b\w/){|s| s.upcase }
+          tmp = key.gsub(/\bwww|^te$|\b\w/){ $&.upcase }
           data << "#{tmp}: #{value}" << CRLF
         }
         @cookies.each{|cookie|
@@ -181,31 +295,44 @@ module WEBrick
       end
     end
 
-    def send_body(socket)
+    ##
+    # Sends the body on +socket+
+
+    def send_body(socket) # :nodoc:
       case @body
       when IO then send_body_io(socket)
       else send_body_string(socket)
       end
     end
 
-    def to_s
+    def to_s # :nodoc:
       ret = ""
       send_response(ret)
       ret
     end
 
+    ##
+    # Redirects to +url+ with a WEBrick::HTTPStatus::Redirect +status+.
+    #
+    # Example:
+    #
+    #   res.set_redirect WEBrick::HTTPStatus::TemporaryRedirect
+
     def set_redirect(status, url)
       @body = "<HTML><A HREF=\"#{url.to_s}\">#{url.to_s}</A>.</HTML>\n"
       @header['location'] = url.to_s
       raise status
     end
 
+    ##
+    # Creates an error page for exception +ex+ with an optional +backtrace+
+
     def set_error(ex, backtrace=false)
       case ex
-      when HTTPStatus::Status 
+      when HTTPStatus::Status
         @keep_alive = false if HTTPStatus::error?(ex.code)
         self.status = ex.code
-      else 
+      else
         @keep_alive = false
         self.status = HTTPStatus::RC_INTERNAL_SERVER_ERROR
       end
@@ -253,18 +380,25 @@ module WEBrick
 
     private
 
+    # :stopdoc:
+
     def send_body_io(socket)
       begin
         if @request_method == "HEAD"
           # do nothing
         elsif chunked?
-          while buf = @body.read(BUFSIZE)
-            next if buf.empty?
-            data = ""
-            data << format("%x", buf.size) << CRLF
-            data << buf << CRLF
-            _write_data(socket, data)
-            @sent_size += buf.size
+          begin
+            buf  = ''
+            data = ''
+            while true
+              @body.readpartial( @buffer_size, buf ) # there is no need to clear buf?
+              data << format("%x", buf.bytesize) << CRLF
+              data << buf << CRLF
+              _write_data(socket, data)
+              data.clear
+              @sent_size += buf.bytesize
+            end
+          rescue EOFError # do nothing
           end
           _write_data(socket, "0#{CRLF}#{CRLF}")
         else
@@ -281,41 +415,41 @@ module WEBrick
       if @request_method == "HEAD"
         # do nothing
       elsif chunked?
-        remain = body ? @body.size : 0
-        while buf = @body[@sent_size, BUFSIZE]
+        body ? @body.bytesize : 0
+        while buf = @body[@sent_size, @buffer_size]
           break if buf.empty?
           data = ""
-          data << format("%x", buf.size) << CRLF
+          data << format("%x", buf.bytesize) << CRLF
           data << buf << CRLF
           _write_data(socket, data)
-          @sent_size += buf.size
+          @sent_size += buf.bytesize
         end
         _write_data(socket, "0#{CRLF}#{CRLF}")
       else
-        if @body && @body.size > 0
+        if @body && @body.bytesize > 0
           _write_data(socket, @body)
-          @sent_size = @body.size
+          @sent_size = @body.bytesize
         end
       end
     end
 
     def _send_file(output, input, offset, size)
       while offset > 0
-        sz = BUFSIZE < offset ? BUFSIZE : offset
+        sz = @buffer_size < size ? @buffer_size : size
         buf = input.read(sz)
-        offset -= buf.size
+        offset -= buf.bytesize
       end
 
       if size == 0
-        while buf = input.read(BUFSIZE)
+        while buf = input.read(@buffer_size)
           _write_data(output, buf)
         end
       else
         while size > 0
-          sz = BUFSIZE < size ? BUFSIZE : size
+          sz = @buffer_size < size ? @buffer_size : size
           buf = input.read(sz)
           _write_data(output, buf)
-          size -= buf.size
+          size -= buf.bytesize
         end
       end
     end
@@ -323,5 +457,8 @@ module WEBrick
     def _write_data(socket, data)
       socket << data
     end
+
+    # :startdoc:
   end
+
 end

data/lib/webrick/https.rb

@@ -15,8 +15,28 @@ module WEBrick
     HTTP.update(SSL)
   end
 
+  ##
+  #--
+  # Adds SSL functionality to WEBrick::HTTPRequest
+
   class HTTPRequest
-    attr_reader :cipher, :server_cert, :client_cert
+
+    ##
+    # HTTP request SSL cipher
+
+    attr_reader :cipher
+
+    ##
+    # HTTP request server certificate
+
+    attr_reader :server_cert
+
+    ##
+    # HTTP request client certificate
+
+    attr_reader :client_cert
+
+    # :stopdoc:
 
     alias orig_parse parse
 
@@ -33,17 +53,18 @@ module WEBrick
     alias orig_parse_uri parse_uri
 
     def parse_uri(str, scheme="https")
-      if @server_cert
+      if server_cert
         return orig_parse_uri(str, scheme)
       end
       return orig_parse_uri(str)
     end
+    private :parse_uri
 
     alias orig_meta_vars meta_vars
 
     def meta_vars
       meta = orig_meta_vars
-      if @server_cert
+      if server_cert
         meta["HTTPS"] = "on"
         meta["SSL_SERVER_CERT"] = @server_cert.to_pem
         meta["SSL_CLIENT_CERT"] = @client_cert ? @client_cert.to_pem : ""
@@ -59,5 +80,7 @@ module WEBrick
       end
       meta
     end
+
+    # :startdoc:
   end
 end

data/lib/webrick/httpserver.rb

@@ -19,9 +19,30 @@ require 'webrick/accesslog'
 module WEBrick
   class HTTPServerError < ServerError; end
 
+  ##
+  # An HTTP Server
+
   class HTTPServer < ::WEBrick::GenericServer
+    ##
+    # Creates a new HTTP server according to +config+
+    #
+    # An HTTP server uses the following attributes:
+    #
+    # :AccessLog:: An array of access logs.  See WEBrick::AccessLog
+    # :BindAddress:: Local address for the server to bind to
+    # :DocumentRoot:: Root path to serve files from
+    # :DocumentRootOptions:: Options for the default HTTPServlet::FileHandler
+    # :HTTPVersion:: The HTTP version of this server
+    # :Port:: Port to listen on
+    # :RequestCallback:: Called with a request and response before each
+    #                    request is serviced.
+    # :RequestTimeout:: Maximum time to wait between requests
+    # :ServerAlias:: Array of alternate names for this server for virtual
+    #                hosting
+    # :ServerName:: Name for this server for virtual hosting
+
     def initialize(config={}, default=Config::HTTP)
-      super
+      super(config, default)
       @http_version = HTTPVersion::convert(@config[:HTTPVersion])
 
       @mount_tab = MountTable.new
@@ -36,12 +57,15 @@ module WEBrick
           [ $stderr, AccessLog::REFERER_LOG_FORMAT ]
         ]
       end
- 
+
       @virtual_hosts = Array.new
     end
 
+    ##
+    # Processes requests on +sock+
+
     def run(sock)
-      while true 
+      while true
         res = HTTPResponse.new(@config)
         req = HTTPRequest.new(@config)
         server = self
@@ -52,14 +76,19 @@ module WEBrick
             timeout = 0 if @status != :Running
             timeout -= 0.5
           end
-          raise HTTPStatus::EOFError if timeout <= 0 || sock.eof?
+          raise HTTPStatus::EOFError if timeout <= 0
+          raise HTTPStatus::EOFError if sock.eof?
           req.parse(sock)
           res.request_method = req.request_method
           res.request_uri = req.request_uri
           res.request_http_version = req.http_version
           res.keep_alive = req.keep_alive?
           server = lookup_server(req) || self
-          if callback = server[:RequestCallback] || server[:RequestHandler]
+          if callback = server[:RequestCallback]
+            callback.call(req, res)
+          elsif callback = server[:RequestHandler]
+            msg = ":RequestHandler is deprecated, please use :RequestCallback"
+            @logger.warn(msg)
             callback.call(req, res)
           end
           server.service(req, res)
@@ -75,7 +104,9 @@ module WEBrick
           res.set_error(ex, true)
         ensure
           if req.request_line
-            req.fixup()
+            if req.keep_alive? && res.keep_alive?
+              req.fixup()
+            end
             res.send_response(sock)
             server.access_log(@config, req, res)
           end
@@ -86,6 +117,9 @@ module WEBrick
       end
     end
 
+    ##
+    # Services +req+ and fills in +res+
+
     def service(req, res)
       if req.unparsed_uri == "*"
         if req.request_method == "OPTIONS"
@@ -104,27 +138,45 @@ module WEBrick
       si.service(req, res)
     end
 
+    ##
+    # The default OPTIONS request handler says GET, HEAD, POST and OPTIONS
+    # requests are allowed.
+
     def do_OPTIONS(req, res)
       res["allow"] = "GET,HEAD,POST,OPTIONS"
     end
 
+    ##
+    # Mounts +servlet+ on +dir+ passing +options+ to the servlet at creation
+    # time
+
     def mount(dir, servlet, *options)
       @logger.debug(sprintf("%s is mounted on %s.", servlet.inspect, dir))
       @mount_tab[dir] = [ servlet, options ]
     end
 
+    ##
+    # Mounts +proc+ or +block+ on +dir+ and calls it with a
+    # WEBrick::HTTPRequest and WEBrick::HTTPResponse
+
     def mount_proc(dir, proc=nil, &block)
       proc ||= block
       raise HTTPServerError, "must pass a proc or block" unless proc
       mount(dir, HTTPServlet::ProcHandler.new(proc))
     end
 
+    ##
+    # Unmounts +dir+
+
     def unmount(dir)
       @logger.debug(sprintf("unmount %s.", dir))
       @mount_tab.delete(dir)
     end
     alias umount unmount
 
+    ##
+    # Finds a servlet for +path+
+
     def search_servlet(path)
       script_name, path_info = @mount_tab.scan(path)
       servlet, options = @mount_tab[script_name]
@@ -133,6 +185,9 @@ module WEBrick
       end
     end
 
+    ##
+    # Adds +server+ as a virtual host.
+
     def virtual_host(server)
       @virtual_hosts << server
       @virtual_hosts = @virtual_hosts.sort_by{|s|
@@ -144,6 +199,9 @@ module WEBrick
       }
     end
 
+    ##
+    # Finds the appropriate virtual host to handle +req+
+
     def lookup_server(req)
       @virtual_hosts.find{|s|
         (s[:BindAddress].nil? || req.addr[3] == s[:BindAddress]) &&
@@ -153,6 +211,10 @@ module WEBrick
       }
     end
 
+    ##
+    # Logs +req+ and +res+ in the access logs.  +config+ is used for the
+    # server name.
+
     def access_log(config, req, res)
       param = AccessLog::setup_params(config, req, res)
       @config[:AccessLog].each{|logger, fmt|
@@ -160,7 +222,13 @@ module WEBrick
       }
     end
 
-    class MountTable
+    ##
+    # Mount table for the path a servlet is mounted on in the directory space
+    # of the server.  Users of WEBrick can only access this indirectly via
+    # WEBrick::HTTPServer#mount, WEBrick::HTTPServer#unmount and
+    # WEBrick::HTTPServer#search_servlet
+
+    class MountTable # :nodoc:
       def initialize
         @tab = Hash.new
         compile