webrick 1.3.1 → 1.5.0

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",
@@ -58,6 +69,7 @@ module WEBrick
       "jpeg"  => "image/jpeg",
       "jpg"   => "image/jpeg",
       "js"    => "application/javascript",
+      "json"  => "application/json",
       "lha"   => "application/octet-stream",
       "lzh"   => "application/octet-stream",
       "mov"   => "video/quicktime",
@@ -83,6 +95,7 @@ module WEBrick
       "tif"   => "image/tiff",
       "tiff"  => "image/tiff",
       "txt"   => "text/plain",
+      "wasm"  => "application/wasm",
       "xbm"   => "image/x-xbitmap",
       "xhtml" => "text/html",
       "xls"   => "application/vnd.ms-excel",
@@ -92,8 +105,12 @@ module WEBrick
       "zip"   => "application/zip",
     }
 
-    # Load Apache compatible mime.types file.
+    ##
+    # Loads Apache-compatible mime.types in +file+.
+
     def load_mime_types(file)
+      # note: +file+ may be a "| command" for now; some people may
+      # rely on this, but currently we do not use this method by default.
       open(file){ |io|
         hash = Hash.new
         io.each{ |line|
@@ -109,6 +126,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 +137,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 +171,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 +198,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 +219,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 +229,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 +282,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves the header at the first entry in +key+
+
       def [](*key)
         begin
           @header[key[0].downcase].join(", ")
@@ -234,6 +293,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 +314,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 +331,9 @@ module WEBrick
         self
       end
 
+      ##
+      # Yields each entry in this FormData
+
       def each_data
         tmp = self
         while tmp
@@ -270,6 +343,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Returns all the FormData as an Array
+
       def list
         ret = []
         each_data{|data|
@@ -278,13 +354,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 +391,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 +438,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 +461,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 +504,9 @@ module WEBrick
       return result
     end
 
+    ##
+    # Escapes 8 bit characters in +str+
+
     def escape8bit(str)
       _escape(str, NONASCII)
     end

data/lib/webrick/httpversion.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: false
 #--
 # HTTPVersion.rb -- presentation of HTTP version
 #
@@ -8,15 +9,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 +51,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 +65,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,3 +1,4 @@
+# frozen_string_literal: false
 #--
 # log.rb -- Log Class
 #
@@ -14,8 +15,27 @@ module WEBrick
   # A generic logging class
 
   class BasicLog
-    # log-level constants
-    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
@@ -31,7 +51,7 @@ module WEBrick
       @level = level || INFO
       case log_file
       when String
-        @log = open(log_file, "a+")
+        @log = File.open(log_file, "a+")
         @log.sync = true
         @opened = true
       when NilClass
@@ -98,10 +118,10 @@ module WEBrick
     # * Otherwise it will return +arg+.inspect.
     def format(arg)
       if arg.is_a?(Exception)
-        "#{arg.class}: #{arg.message}\n\t" <<
+        "#{arg.class}: #{AccessLog.escape(arg.message)}\n\t" <<
         arg.backtrace.join("\n\t") << "\n"
       elsif arg.respond_to?(:to_str)
-        arg.to_str
+        AccessLog.escape(arg.to_str)
       else
         arg.inspect
       end