rubysl-webrick 1.0.0 → 2.0.0

data/lib/webrick/compat.rb

@@ -8,8 +8,28 @@
 #
 # $IPR: compat.rb,v 1.6 2002/10/01 17:16:32 gotoyuzo Exp $
 
+##
+# System call error module used by webrick for cross platform compatability.
+#
+# EPROTO:: protocol error
+# ECONNRESET:: remote host reset the connection request
+# ECONNABORTED:: Client sent TCP reset (RST) before server has accepted the
+#                connection requested by client.
+#
 module Errno
+  ##
+  # Protocol error.
+
   class EPROTO       < SystemCallError; end
+
+  ##
+  # Remote host reset the connection request.
+
   class ECONNRESET   < SystemCallError; end
+
+  ##
+  # Client sent TCP reset (RST) before server has accepted the connection
+  # requested by client.
+
   class ECONNABORTED < SystemCallError; end
 end

data/lib/webrick/config.rb

@@ -16,13 +16,13 @@ require 'webrick/log'
 
 module WEBrick
   module Config
-    LIBDIR = File::dirname(__FILE__)
+    LIBDIR = File::dirname(__FILE__) # :nodoc:
 
     # for GenericServer
     General = {
       :ServerName     => Utils::getservername,
       :BindAddress    => nil,   # "0.0.0.0" or "::" or nil
-      :Port           => nil,   # users MUST specifiy this!!
+      :Port           => nil,   # users MUST specify this!!
       :MaxClients     => 100,   # maximum number of the concurrent connections
       :ServerType     => nil,   # default: WEBrick::SimpleServer
       :Logger         => nil,   # default: WEBrick::Log.new
@@ -33,6 +33,8 @@ module WEBrick
       :StartCallback  => nil,
       :StopCallback   => nil,
       :AcceptCallback => nil,
+      :DoNotReverseLookup => nil,
+      :ShutdownSocketWithoutClose => false,
     }
 
     # for HTTPServer, HTTPRequest, HTTPResponse ...
@@ -45,9 +47,10 @@ module WEBrick
       :DirectoryIndex => ["index.html","index.htm","index.cgi","index.rhtml"],
       :DocumentRoot   => nil,
       :DocumentRootOptions => { :FancyIndexing => true },
-      :RequestHandler => nil,
-      :RequestCallback => nil,  # alias of :RequestHandler
+      :RequestCallback => nil,
       :ServerAlias    => nil,
+      :InputBufferSize  => 65536, # input buffer size in reading request body
+      :OutputBufferSize => 65536, # output buffer size in sending File or IO
 
       # for HTTPProxyServer
       :ProxyAuthProc  => nil,
@@ -64,6 +67,30 @@ module WEBrick
       :Escape8bitURI  => false
     )
 
+    ##
+    # Default configuration for WEBrick::HTTPServlet::FileHandler
+    #
+    # :AcceptableLanguages::
+    #   Array of languages allowed for accept-language.  There is no default
+    # :DirectoryCallback::
+    #   Allows preprocessing of directory requests.  There is no default
+    #   callback.
+    # :FancyIndexing::
+    #   If true, show an index for directories.  The default is true.
+    # :FileCallback::
+    #   Allows preprocessing of file requests.  There is no default callback.
+    # :HandlerCallback::
+    #   Allows preprocessing of requests.  There is no default callback.
+    # :HandlerTable::
+    #   Maps file suffixes to file handlers.  DefaultFileHandler is used by
+    #   default but any servlet can be used.
+    # :NondisclosureName::
+    #   Do not show files matching this array of globs.  .ht* and *~ are
+    #   excluded by default.
+    # :UserDir::
+    #   Directory inside ~user to serve content from for /~user requests.
+    #   Only works if mounted on /.  Disabled by default.
+
     FileHandler = {
       :NondisclosureName => [".ht*", "*~"],
       :FancyIndexing     => false,
@@ -75,12 +102,39 @@ module WEBrick
       :AcceptableLanguages => []  # ["en", "ja", ... ]
     }
 
+    ##
+    # Default configuration for WEBrick::HTTPAuth::BasicAuth
+    #
+    # :AutoReloadUserDB:: Reload the user database provided by :UserDB
+    #                     automatically?
+
     BasicAuth = {
       :AutoReloadUserDB     => true,
     }
 
+    ##
+    # Default configuration for WEBrick::HTTPAuth::DigestAuth.
+    #
+    # :Algorithm:: MD5, MD5-sess (default), SHA1, SHA1-sess
+    # :Domain:: An Array of URIs that define the protected space
+    # :Qop:: 'auth' for authentication, 'auth-int' for integrity protection or
+    #        both
+    # :UseOpaque:: Should the server send opaque values to the client?  This
+    #              helps prevent replay attacks.
+    # :CheckNc:: Should the server check the nonce count?  This helps the
+    #            server detect replay attacks.
+    # :UseAuthenticationInfoHeader:: Should the server send an
+    #                                AuthenticationInfo header?
+    # :AutoReloadUserDB:: Reload the user database provided by :UserDB
+    #                     automatically?
+    # :NonceExpirePeriod:: How long should we store used nonces?  Default is
+    #                      30 minutes.
+    # :NonceExpireDelta:: How long is a nonce valid?  Default is 1 minute
+    # :InternetExplorerHack:: Hack which allows Internet Explorer to work.
+    # :OperaHack:: Hack which allows Opera to work.
+
     DigestAuth = {
-      :Algorithm            => 'MD5-sess', # or 'MD5' 
+      :Algorithm            => 'MD5-sess', # or 'MD5'
       :Domain               => nil,        # an array includes domain names.
       :Qop                  => [ 'auth' ], # 'auth' or 'auth-int' or both.
       :UseOpaque            => true,

data/lib/webrick/cookie.rb

@@ -12,14 +12,56 @@ require 'time'
 require 'webrick/httputils'
 
 module WEBrick
+
+  ##
+  # Processes HTTP cookies
+
   class Cookie
 
+    ##
+    # The cookie name
+
     attr_reader :name
-    attr_accessor :value, :version
-    attr_accessor :domain, :path, :secure
-    attr_accessor :comment, :max_age
+
+    ##
+    # The cookie value
+
+    attr_accessor :value
+
+    ##
+    # The cookie version
+
+    attr_accessor :version
+
+    ##
+    # The cookie domain
+    attr_accessor :domain
+
+    ##
+    # The cookie path
+
+    attr_accessor :path
+
+    ##
+    # Is this a secure cookie?
+
+    attr_accessor :secure
+
+    ##
+    # The cookie comment
+
+    attr_accessor :comment
+
+    ##
+    # The maximum age of the cookie
+
+    attr_accessor :max_age
+
     #attr_accessor :comment_url, :discard, :port
 
+    ##
+    # Creates a new cookie with the given +name+ and +value+
+
     def initialize(name, value)
       @name = name
       @value = value
@@ -29,14 +71,25 @@ module WEBrick
       @expires = @comment_url = @discard = @port = nil
     end
 
+    ##
+    # Sets the cookie expiration to the time +t+.  The expiration time may be
+    # a false value to disable expiration or a Time or HTTP format time string
+    # to set the expiration date.
+
     def expires=(t)
       @expires = t && (t.is_a?(Time) ? t.httpdate : t.to_s)
     end
 
+    ##
+    # Retrieves the expiration time as a Time
+
     def expires
       @expires && Time.parse(@expires)
     end
 
+    ##
+    # The cookie string suitable for use in an HTTP header
+
     def to_s
       ret = ""
       ret << @name << "=" << @value
@@ -50,8 +103,10 @@ module WEBrick
       ret
     end
 
-    # Cookie::parse()
-    #   It parses Cookie field sent from the user agent.
+    ##
+    # Parses a Cookie field sent from the user-agent.  Returns an array of
+    # cookies.
+
     def self.parse(str)
       if str
         ret = []
@@ -76,6 +131,9 @@ module WEBrick
       end
     end
 
+    ##
+    # Parses the cookie in +str+
+
     def self.parse_set_cookie(str)
       cookie_elem = str.split(/;/)
       first_elem = cookie_elem.shift
@@ -101,6 +159,9 @@ module WEBrick
       return cookie
     end
 
+    ##
+    # Parses the cookies in +str+
+
     def self.parse_set_cookies(str)
       return str.split(/,(?=[^;,]*=)|,$/).collect{|c|
         parse_set_cookie(c)

data/lib/webrick/htmlutils.rb

@@ -1,4 +1,4 @@
-#
+#--
 # htmlutils.rb -- HTMLUtils Module
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -11,6 +11,9 @@
 module WEBrick
   module HTMLUtils
 
+    ##
+    # Escapes &, ", > and < in +string+
+
     def escape(string)
       str = string ? string.dup : ""
       str.gsub!(/&/n, '&amp;')

data/lib/webrick/httpauth.rb

@@ -15,10 +15,46 @@ require 'webrick/httpauth/htdigest'
 require 'webrick/httpauth/htgroup'
 
 module WEBrick
+
+  ##
+  # HTTPAuth provides both basic and digest authentication.
+  #
+  # To enable authentication for requests in WEBrick you will need a user
+  # database and an authenticator.  To start, here's an Htpasswd database for
+  # use with a DigestAuth authenticator:
+  #
+  #   config = { :Realm => 'DigestAuth example realm' }
+  #
+  #   htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
+  #   htpasswd.auth_type = WEBrick::HTTPAuth::DigestAuth
+  #   htpasswd.set_passwd config[:Realm], 'username', 'password'
+  #   htpasswd.flush
+  #
+  # The +:Realm+ is used to provide different access to different groups
+  # across several resources on a server.  Typically you'll need only one
+  # realm for a server.
+  #
+  # This database can be used to create an authenticator:
+  #
+  #   config[:UserDB] = htpasswd
+  #
+  #   digest_auth = WEBrick::HTTPAuth::DigestAuth.new config
+  #
+  # To authenticate a request call #authenticate with a request and response
+  # object in a servlet:
+  #
+  #   def do_GET req, res
+  #     @authenticator.authenticate req, res
+  #   end
+  #
+  # For digest authentication the authenticator must not be created every
+  # request, it must be passed in as an option via WEBrick::HTTPServer#mount.
+
   module HTTPAuth
     module_function
 
-    def _basic_auth(req, res, realm, req_field, res_field, err_type, block)
+    def _basic_auth(req, res, realm, req_field, res_field, err_type,
+                    block) # :nodoc:
       user = pass = nil
       if /^Basic\s+(.*)/o =~ req[req_field]
         userpass = $1
@@ -32,12 +68,26 @@ module WEBrick
       raise err_type
     end
 
-    def basic_auth(req, res, realm, &block)
+    ##
+    # Simple wrapper for providing basic authentication for a request.  When
+    # called with a request +req+, response +res+, authentication +realm+ and
+    # +block+ the block will be called with a +username+ and +password+.  If
+    # the block returns true the request is allowed to continue, otherwise an
+    # HTTPStatus::Unauthorized error is raised.
+
+    def basic_auth(req, res, realm, &block) # :yield: username, password
       _basic_auth(req, res, realm, "Authorization", "WWW-Authenticate",
                   HTTPStatus::Unauthorized, block)
     end
 
-    def proxy_basic_auth(req, res, realm, &block)
+    ##
+    # Simple wrapper for providing basic authentication for a proxied request.
+    # When called with a request +req+, response +res+, authentication +realm+
+    # and +block+ the block will be called with a +username+ and +password+.
+    # If the block returns true the request is allowed to continue, otherwise
+    # an HTTPStatus::ProxyAuthenticationRequired error is raised.
+
+    def proxy_basic_auth(req, res, realm, &block) # :yield: username, password
       _basic_auth(req, res, realm, "Proxy-Authorization", "Proxy-Authenticate",
                   HTTPStatus::ProxyAuthenticationRequired, block)
     end

data/lib/webrick/httpauth/authenticator.rb

@@ -1,4 +1,4 @@
-#
+#--
 # httpauth/authenticator.rb -- Authenticator mix-in module.
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -9,23 +9,51 @@
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Module providing generic support for both Digest and Basic
+    # authentication schemes.
+
     module Authenticator
-      RequestField      = "Authorization"
-      ResponseField     = "WWW-Authenticate"
-      ResponseInfoField = "Authentication-Info"
-      AuthException     = HTTPStatus::Unauthorized
-      AuthScheme        = nil # must override by the derived class
 
-      attr_reader :realm, :userdb, :logger
+      RequestField      = "Authorization" # :nodoc:
+      ResponseField     = "WWW-Authenticate" # :nodoc:
+      ResponseInfoField = "Authentication-Info" # :nodoc:
+      AuthException     = HTTPStatus::Unauthorized # :nodoc:
+
+      ##
+      # Method of authentication, must be overridden by the including class
+
+      AuthScheme        = nil
+
+      ##
+      # The realm this authenticator covers
+
+      attr_reader :realm
+
+      ##
+      # The user database for this authenticator
+
+      attr_reader :userdb
+
+      ##
+      # The logger for this authenticator
+
+      attr_reader :logger
 
       private
 
+      # :stopdoc:
+
+      ##
+      # Initializes the authenticator from +config+
+
       def check_init(config)
         [:UserDB, :Realm].each{|sym|
           unless config[sym]
             raise ArgumentError, "Argument #{sym.inspect} missing."
           end
-        } 
+        }
         @realm     = config[:Realm]
         @userdb    = config[:UserDB]
         @logger    = config[:Logger] || Log::new($stderr)
@@ -37,12 +65,15 @@ module WEBrick
         @auth_scheme     = self::class::AuthScheme
       end
 
+      ##
+      # Ensures +req+ has credentials that can be authenticated.
+
       def check_scheme(req)
         unless credentials = req[@request_field]
           error("no credentials in the request.")
-          return nil 
-        end  
-        unless match = /^#{@auth_scheme}\s+/.match(credentials)
+          return nil
+        end
+        unless match = /^#{@auth_scheme}\s+/i.match(credentials)
           error("invalid scheme in %s.", credentials)
           info("%s: %s", @request_field, credentials) if $DEBUG
           return nil
@@ -60,20 +91,26 @@ module WEBrick
         if @logger.error?
           log(:error, fmt, *args)
         end
-      end                             
+      end
 
       def info(fmt, *args)
         if @logger.info?
           log(:info, fmt, *args)
         end
       end
+
+      # :startdoc:
     end
 
+    ##
+    # Module providing generic support for both Digest and Basic
+    # authentication schemes for proxies.
+
     module ProxyAuthenticator
-      RequestField  = "Proxy-Authorization"
-      ResponseField = "Proxy-Authenticate"
-      InfoField     = "Proxy-Authentication-Info"
-      AuthException = HTTPStatus::ProxyAuthenticationRequired
+      RequestField  = "Proxy-Authorization" # :nodoc:
+      ResponseField = "Proxy-Authenticate" # :nodoc:
+      InfoField     = "Proxy-Authentication-Info" # :nodoc:
+      AuthException = HTTPStatus::ProxyAuthenticationRequired # :nodoc:
     end
   end
 end