webrick 1.3.1 → 1.4.0.beta1

data/lib/webrick/httpservlet/prochandler.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: false
 #
 # prochandler.rb -- ProcHandler Class
 #
@@ -13,7 +14,19 @@ 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
@@ -27,6 +40,7 @@ module WEBrick
       end
 
       alias do_POST do_GET
+      # :startdoc:
     end
 
   end

data/lib/webrick/httpstatus.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: false
 #--
 # httpstatus.rb -- HTTPStatus Class
 #
@@ -8,6 +9,8 @@
 #
 # $IPR: httpstatus.rb,v 1.11 2003/03/24 20:18:55 gotoyuzo Exp $
 
+require 'webrick/accesslog'
+
 module WEBrick
 
   ##
@@ -27,19 +30,19 @@ module WEBrick
       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
+    # Root of the HTTP success statuses
     class Success     < Status; end
     # Root of the HTTP redirect statuses
     class Redirect    < Status; end
@@ -63,6 +66,7 @@ module WEBrick
       204 => 'No Content',
       205 => 'Reset Content',
       206 => 'Partial Content',
+      207 => 'Multi-Status',
       300 => 'Multiple Choices',
       301 => 'Moved Permanently',
       302 => 'Found',
@@ -88,12 +92,22 @@ 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',
+      451 => 'Unavailable For Legal Reasons',
       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',
     }
 
     # Maps a status code to the corresponding Status class
@@ -136,31 +150,31 @@ module WEBrick
     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)

data/lib/webrick/httputils.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: false
 #
 # httputils.rb -- HTTPUtils Module
 #
@@ -12,12 +13,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 +41,8 @@ module WEBrick
     end
     module_function :normalize_path
 
-    #####
+    ##
+    # Default mime types
 
     DefaultMimeTypes = {
       "ai"    => "application/postscript",
@@ -92,7 +103,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
@@ -109,6 +122,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)
@@ -116,7 +133,9 @@ 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)
@@ -148,12 +167,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)
@@ -169,6 +194,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
@@ -187,7 +215,8 @@ module WEBrick
     end
     module_function :parse_qvalues
 
-    #####
+    ##
+    # Removes quotes and escapes from +str+
 
     def dequote(str)
       ret = (/\A"(.*)"\Z/ =~ str) ? $1 : str.dup
@@ -196,20 +225,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
 
-      attr_accessor :name, :filename, :next_data
+      ##
+      # 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?
@@ -226,6 +278,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves the header at the first entry in +key+
+
       def [](*key)
         begin
           @header[key[0].downcase].join(", ")
@@ -234,6 +289,12 @@ 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
@@ -249,6 +310,11 @@ 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
@@ -261,6 +327,9 @@ module WEBrick
         self
       end
 
+      ##
+      # Yields each entry in this FormData
+
       def each_data
         tmp = self
         while tmp
@@ -270,6 +339,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Returns all the FormData as an Array
+
       def list
         ret = []
         each_data{|data|
@@ -278,13 +350,22 @@ 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
@@ -306,6 +387,9 @@ 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--#{Regexp.quote(boundary)}(--)?#{CRLF}\z/
       form_data = Hash.new
@@ -350,10 +434,22 @@ 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.ord } end
-    def _unescape(str, regex) str.gsub(regex){ $1.hex.chr } end
+    def _escape(str, regex)
+      str = str.b
+      str.gsub!(regex) {"%%%02X" % $1.ord}
+      # %-escaped string should contain US-ASCII only
+      str.force_encoding(Encoding::US_ASCII)
+    end
+    def _unescape(str, regex)
+      str = str.b
+      str.gsub!(regex) {$1.hex.chr}
+      # encoding of %-unescaped string is unknown
+      str
+    end
 
     UNESCAPED = _make_regex(control+space+delims+unwise+nonascii)
     UNESCAPED_FORM = _make_regex(reserved+control+delims+unwise+nonascii)
@@ -361,24 +457,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|
@@ -387,6 +500,9 @@ module WEBrick
       return result
     end
 
+    ##
+    # Escapes 8 bit characters in +str+
+
     def escape8bit(str)
       _escape(str, NONASCII)
     end