rubysl-webrick 1.0.0 → 2.0.0

data/lib/webrick/httpservlet/prochandler.rb

@@ -1,11 +1,11 @@
-# 
+#
 # prochandler.rb -- ProcHandler Class
-#       
+#
 # Author: IPR -- Internet Programming with Ruby -- writers
 # Copyright (c) 2001 TAKAHASHI Masayoshi, GOTOU Yuuzou
 # Copyright (c) 2002 Internet Programming with Ruby writers. All rights
 # reserved.
-#   
+#
 # $IPR: prochandler.rb,v 1.7 2002/09/21 12:23:42 gotoyuzo Exp $
 
 require 'webrick/httpservlet/abstract.rb'
@@ -13,10 +13,22 @@ require 'webrick/httpservlet/abstract.rb'
 module WEBrick
   module HTTPServlet
 
+    ##
+    # Mounts a proc at a path that accepts a request and response.
+    #
+    # Instead of mounting this servlet with WEBrick::HTTPServer#mount use
+    # WEBrick::HTTPServer#mount_proc:
+    #
+    #   server.mount_proc '/' do |req, res|
+    #     res.body = 'it worked!'
+    #     res.status = 200
+    #   end
+
     class ProcHandler < AbstractServlet
+      # :stopdoc:
       def get_instance(server, *options)
         self
-      end  
+      end
 
       def initialize(proc)
         @proc = proc
@@ -27,6 +39,7 @@ module WEBrick
       end
 
       alias do_POST do_GET
+      # :startdoc:
     end
 
   end

data/lib/webrick/httpstatus.rb

@@ -1,4 +1,4 @@
-#
+#--
 # httpstatus.rb -- HTTPStatus Class
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -10,19 +10,50 @@
 
 module WEBrick
 
+  ##
+  # This module is used to manager HTTP status codes.
+  #
+  # See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more
+  # information.
   module HTTPStatus
 
-    class Status      < StandardError; end
+    ##
+    # Root of the HTTP status class hierarchy
+    class Status < StandardError
+      def initialize(*args) # :nodoc:
+        args[0] = AccessLog.escape(args[0]) unless args.empty?
+        super(*args)
+      end
+      class << self
+        attr_reader :code, :reason_phrase # :nodoc:
+      end
+
+      # Returns the HTTP status code
+      def code() self::class::code end
+
+      # Returns the HTTP status description
+      def reason_phrase() self::class::reason_phrase end
+
+      alias to_i code # :nodoc:
+    end
+
+    # Root of the HTTP info statuses
     class Info        < Status; end
+    # Root of the HTTP sucess statuses
     class Success     < Status; end
+    # Root of the HTTP redirect statuses
     class Redirect    < Status; end
+    # Root of the HTTP error statuses
     class Error       < Status; end
+    # Root of the HTTP client error statuses
     class ClientError < Error; end
+    # Root of the HTTP server error statuses
     class ServerError < Error; end
-    
+
     class EOFError < StandardError; end
 
-    StatusMessage = {
+    # HTTP status codes and descriptions
+    StatusMessage = { # :nodoc:
       100 => 'Continue',
       101 => 'Switching Protocols',
       200 => 'OK',
@@ -32,6 +63,7 @@ module WEBrick
       204 => 'No Content',
       205 => 'Reset Content',
       206 => 'Partial Content',
+      207 => 'Multi-Status',
       300 => 'Multiple Choices',
       301 => 'Moved Permanently',
       302 => 'Found',
@@ -57,17 +89,30 @@ module WEBrick
       415 => 'Unsupported Media Type',
       416 => 'Request Range Not Satisfiable',
       417 => 'Expectation Failed',
+      422 => 'Unprocessable Entity',
+      423 => 'Locked',
+      424 => 'Failed Dependency',
+      426 => 'Upgrade Required',
+      428 => 'Precondition Required',
+      429 => 'Too Many Requests',
+      431 => 'Request Header Fields Too Large',
       500 => 'Internal Server Error',
       501 => 'Not Implemented',
       502 => 'Bad Gateway',
       503 => 'Service Unavailable',
       504 => 'Gateway Timeout',
-      505 => 'HTTP Version Not Supported'
+      505 => 'HTTP Version Not Supported',
+      507 => 'Insufficient Storage',
+      511 => 'Network Authentication Required',
     }
 
-    CodeToError = {}
+    # Maps a status code to the corresponding Status class
+    CodeToError = {} # :nodoc:
 
+    # Creates a status or error class for each status code and
+    # populates the CodeToError map.
     StatusMessage.each{|code, message|
+      message.freeze
       var_name = message.gsub(/[ \-]/,'_').upcase
       err_name = message.gsub(/[ \-]/,'')
 
@@ -79,42 +124,65 @@ module WEBrick
       when 500...600; parent = ServerError
       end
 
-      eval %-
-        RC_#{var_name} = #{code}
-        class #{err_name} < #{parent}
-          def self.code() RC_#{var_name} end
-          def self.reason_phrase() StatusMessage[code] end
-          def code() self::class::code end 
-          def reason_phrase() self::class::reason_phrase end
-          alias to_i code
-        end
-      -
-
-      CodeToError[code] = const_get(err_name)
+      const_set("RC_#{var_name}", code)
+      err_class = Class.new(parent)
+      err_class.instance_variable_set(:@code, code)
+      err_class.instance_variable_set(:@reason_phrase, message)
+      const_set(err_name, err_class)
+      CodeToError[code] = err_class
     }
 
+    ##
+    # Returns the description corresponding to the HTTP status +code+
+    #
+    #   WEBrick::HTTPStatus.reason_phrase 404
+    #   => "Not Found"
     def reason_phrase(code)
       StatusMessage[code.to_i]
     end
+
+    ##
+    # Is +code+ an informational status?
     def info?(code)
       code.to_i >= 100 and code.to_i < 200
     end
+
+    ##
+    # Is +code+ a successful status?
     def success?(code)
       code.to_i >= 200 and code.to_i < 300
     end
+
+    ##
+    # Is +code+ a redirection status?
     def redirect?(code)
       code.to_i >= 300 and code.to_i < 400
     end
+
+    ##
+    # Is +code+ an error status?
     def error?(code)
       code.to_i >= 400 and code.to_i < 600
     end
+
+    ##
+    # Is +code+ a client error status?
     def client_error?(code)
       code.to_i >= 400 and code.to_i < 500
     end
+
+    ##
+    # Is +code+ a server error status?
     def server_error?(code)
       code.to_i >= 500 and code.to_i < 600
     end
 
+    ##
+    # Returns the status class corresponding to +code+
+    #
+    #   WEBrick::HTTPStatus[302]
+    #   => WEBrick::HTTPStatus::NotFound
+    #
     def self.[](code)
       CodeToError[code]
     end

data/lib/webrick/httputils.rb

@@ -12,12 +12,21 @@ require 'socket'
 require 'tempfile'
 
 module WEBrick
-  CR   = "\x0d"
-  LF   = "\x0a"
-  CRLF = "\x0d\x0a"
+  CR   = "\x0d"     # :nodoc:
+  LF   = "\x0a"     # :nodoc:
+  CRLF = "\x0d\x0a" # :nodoc:
+
+  ##
+  # HTTPUtils provides utility methods for working with the HTTP protocol.
+  #
+  # This module is generally used internally by WEBrick
 
   module HTTPUtils
 
+    ##
+    # Normalizes a request path.  Raises an exception if the path cannot be
+    # normalized.
+
     def normalize_path(path)
       raise "abnormal path `#{path}'" if path[0] != ?/
       ret = path.dup
@@ -31,7 +40,8 @@ module WEBrick
     end
     module_function :normalize_path
 
-    #####
+    ##
+    # Default mime types
 
     DefaultMimeTypes = {
       "ai"    => "application/postscript",
@@ -57,6 +67,7 @@ module WEBrick
       "jpe"   => "image/jpeg",
       "jpeg"  => "image/jpeg",
       "jpg"   => "image/jpeg",
+      "js"    => "application/javascript",
       "lha"   => "application/octet-stream",
       "lzh"   => "application/octet-stream",
       "mov"   => "video/quicktime",
@@ -78,10 +89,12 @@ module WEBrick
       "rtf"   => "application/rtf",
       "sgm"   => "text/sgml",
       "sgml"  => "text/sgml",
+      "svg"   => "image/svg+xml",
       "tif"   => "image/tiff",
       "tiff"  => "image/tiff",
       "txt"   => "text/plain",
       "xbm"   => "image/x-xbitmap",
+      "xhtml" => "text/html",
       "xls"   => "application/vnd.ms-excel",
       "xml"   => "text/xml",
       "xpm"   => "image/x-xpixmap",
@@ -89,7 +102,9 @@ module WEBrick
       "zip"   => "application/zip",
     }
 
-    # Load Apache compatible mime.types file.
+    ##
+    # Loads Apache-compatible mime.types in +file+.
+
     def load_mime_types(file)
       open(file){ |io|
         hash = Hash.new
@@ -97,7 +112,7 @@ module WEBrick
           next if /^#/ =~ line
           line.chomp!
           mimetype, ext0 = line.split(/\s+/, 2)
-          next unless ext0   
+          next unless ext0
           next if ext0.empty?
           ext0.split(/\s+/).each{ |ext| hash[ext] = mimetype }
         }
@@ -106,6 +121,10 @@ module WEBrick
     end
     module_function :load_mime_types
 
+    ##
+    # Returns the mime type of +filename+ from the list in +mime_tab+.  If no
+    # mime type was found application/octet-stream is returned.
+
     def mime_type(filename, mime_tab)
       suffix1 = (/\.(\w+)$/ =~ filename && $1.downcase)
       suffix2 = (/\.(\w+)\.[\w\-]+$/ =~ filename && $1.downcase)
@@ -113,12 +132,14 @@ module WEBrick
     end
     module_function :mime_type
 
-    #####
+    ##
+    # Parses an HTTP header +raw+ into a hash of header fields with an Array
+    # of values.
 
     def parse_header(raw)
       header = Hash.new([].freeze)
       field = nil
-      raw.each{|line|
+      raw.each_line{|line|
         case line
         when /^([A-Za-z0-9!\#$%&'*+\-.^_`|~]+):\s*(.*?)\s*\z/om
           field, value = $1, $2
@@ -128,11 +149,11 @@ module WEBrick
         when /^\s+(.*?)\s*\z/om
           value = $1
           unless field
-            raise "bad header '#{line.inspect}'."
+            raise HTTPStatus::BadRequest, "bad header '#{line}'."
           end
           header[field][-1] << " " << value
         else
-          raise "bad header '#{line.inspect}'."
+          raise HTTPStatus::BadRequest, "bad header '#{line}'."
         end
       }
       header.each{|key, values|
@@ -145,12 +166,18 @@ module WEBrick
     end
     module_function :parse_header
 
+    ##
+    # Splits a header value +str+ according to HTTP specification.
+
     def split_header_value(str)
       str.scan(%r'\G((?:"(?:\\.|[^"])+?"|[^",]+)+)
                     (?:,\s*|\Z)'xn).flatten
     end
     module_function :split_header_value
 
+    ##
+    # Parses a Range header value +ranges_specifier+
+
     def parse_range_header(ranges_specifier)
       if /^bytes=(.*)/ =~ ranges_specifier
         byte_range_set = split_header_value($1)
@@ -166,6 +193,9 @@ module WEBrick
     end
     module_function :parse_range_header
 
+    ##
+    # Parses q values in +value+ as used in Accept headers.
+
     def parse_qvalues(value)
       tmp = []
       if value
@@ -184,7 +214,8 @@ module WEBrick
     end
     module_function :parse_qvalues
 
-    #####
+    ##
+    # Removes quotes and escapes from +str+
 
     def dequote(str)
       ret = (/\A"(.*)"\Z/ =~ str) ? $1 : str.dup
@@ -193,20 +224,43 @@ module WEBrick
     end
     module_function :dequote
 
+    ##
+    # Quotes and escapes quotes in +str+
+
     def quote(str)
       '"' << str.gsub(/[\\\"]/o, "\\\1") << '"'
     end
     module_function :quote
 
-    #####
+    ##
+    # Stores multipart form data.  FormData objects are created when
+    # WEBrick::HTTPUtils.parse_form_data is called.
 
     class FormData < String
-      EmptyRawHeader = [].freeze
-      EmptyHeader = {}.freeze
+      EmptyRawHeader = [].freeze # :nodoc:
+      EmptyHeader = {}.freeze # :nodoc:
+
+      ##
+      # The name of the form data part
 
-      attr_accessor :name, :filename, :next_data
+      attr_accessor :name
+
+      ##
+      # The filename of the form data part
+
+      attr_accessor :filename
+
+      attr_accessor :next_data # :nodoc:
       protected :next_data
 
+      ##
+      # Creates a new FormData object.
+      #
+      # +args+ is an Array of form data entries.  One FormData will be created
+      # for each entry.
+      #
+      # This is called by WEBrick::HTTPUtils.parse_form_data for you
+
       def initialize(*args)
         @name = @filename = @next_data = nil
         if args.empty?
@@ -215,7 +269,7 @@ module WEBrick
           super("")
         else
           @raw_header = EmptyRawHeader
-          @header = EmptyHeader 
+          @header = EmptyHeader
           super(args.shift)
           unless args.empty?
             @next_data = self.class.new(*args)
@@ -223,6 +277,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves the header at the first entry in +key+
+
       def [](*key)
         begin
           @header[key[0].downcase].join(", ")
@@ -231,11 +288,17 @@ module WEBrick
         end
       end
 
+      ##
+      # Adds +str+ to this FormData which may be the body, a header or a
+      # header entry.
+      #
+      # This is called by WEBrick::HTTPUtils.parse_form_data for you
+
       def <<(str)
         if @header
           super
         elsif str == CRLF
-          @header = HTTPUtils::parse_header(@raw_header)
+          @header = HTTPUtils::parse_header(@raw_header.join)
           if cd = self['content-disposition']
             if /\s+name="(.*?)"/ =~ cd then @name = $1 end
             if /\s+filename="(.*?)"/ =~ cd then @filename = $1 end
@@ -246,10 +309,15 @@ module WEBrick
         self
       end
 
+      ##
+      # Adds +data+ at the end of the chain of entries
+      #
+      # This is called by WEBrick::HTTPUtils.parse_form_data for you.
+
       def append_data(data)
         tmp = self
         while tmp
-          unless tmp.next_data 
+          unless tmp.next_data
             tmp.next_data = data
             break
           end
@@ -258,6 +326,9 @@ module WEBrick
         self
       end
 
+      ##
+      # Yields each entry in this FormData
+
       def each_data
         tmp = self
         while tmp
@@ -267,6 +338,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Returns all the FormData as an Array
+
       def list
         ret = []
         each_data{|data|
@@ -275,18 +349,27 @@ module WEBrick
         ret
       end
 
+      ##
+      # A FormData will behave like an Array
+
       alias :to_ary :list
 
+      ##
+      # This FormData's body
+
       def to_s
         String.new(self)
       end
     end
 
+    ##
+    # Parses the query component of a URI in +str+
+
     def parse_query(str)
       query = Hash.new
       if str
         str.split(/[&;]/).each{|x|
-          next if x.empty? 
+          next if x.empty?
           key, val = x.split(/=/,2)
           key = unescape_form(key)
           val = unescape_form(val.to_s)
@@ -303,12 +386,15 @@ module WEBrick
     end
     module_function :parse_query
 
+    ##
+    # Parses form data in +io+ with the given +boundary+
+
     def parse_form_data(io, boundary)
-      boundary_regexp = /\A--#{boundary}(--)?#{CRLF}\z/
+      boundary_regexp = /\A--#{Regexp.quote(boundary)}(--)?#{CRLF}\z/
       form_data = Hash.new
       return form_data unless io
       data = nil
-      io.each{|line|
+      io.each_line{|line|
         if boundary_regexp =~ line
           if data
             data.chop!
@@ -316,7 +402,7 @@ module WEBrick
             if form_data.has_key?(key)
               form_data[key].append_data(data)
             else
-              form_data[key] = data 
+              form_data[key] = data
             end
           end
           data = FormData.new
@@ -347,9 +433,11 @@ module WEBrick
 
     module_function
 
+    # :stopdoc:
+
     def _make_regex(str) /([#{Regexp.escape(str)}])/n end
     def _make_regex!(str) /([^#{Regexp.escape(str)}])/n end
-    def _escape(str, regex) str.gsub(regex){ "%%%02X" % $1[0] } end
+    def _escape(str, regex) str.gsub(regex){ "%%%02X" % $1.ord } end
     def _unescape(str, regex) str.gsub(regex){ $1.hex.chr } end
 
     UNESCAPED = _make_regex(control+space+delims+unwise+nonascii)
@@ -358,24 +446,41 @@ module WEBrick
     ESCAPED   = /%([0-9a-fA-F]{2})/
     UNESCAPED_PCHAR = _make_regex!(unreserved+":@&=+$,")
 
+    # :startdoc:
+
+    ##
+    # Escapes HTTP reserved and unwise characters in +str+
+
     def escape(str)
       _escape(str, UNESCAPED)
     end
 
+    ##
+    # Unescapes HTTP reserved and unwise characters in +str+
+
     def unescape(str)
       _unescape(str, ESCAPED)
     end
 
+    ##
+    # Escapes form reserved characters in +str+
+
     def escape_form(str)
       ret = _escape(str, UNESCAPED_FORM)
       ret.gsub!(/ /, "+")
       ret
     end
 
+    ##
+    # Unescapes form reserved characters in +str+
+
     def unescape_form(str)
       _unescape(str.gsub(/\+/, " "), ESCAPED)
     end
 
+    ##
+    # Escapes path +str+
+
     def escape_path(str)
       result = ""
       str.scan(%r{/([^/]*)}).each{|i|
@@ -384,6 +489,9 @@ module WEBrick
       return result
     end
 
+    ##
+    # Escapes 8 bit characters in +str+
+
     def escape8bit(str)
       _escape(str, NONASCII)
     end