* lib/webrick: Add Documentation

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31499 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,7 @@
+Tue May 10 09:13:21 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/webrick: Add Documentation
+
 Tue May 10 04:22:09  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/webrick/log.rb: Hide copyright info from ri

lib/webrick.rb

@@ -1,13 +1,205 @@
+##
+# = WEB server toolkit.
 #
-# WEBrick -- WEB server toolkit.
+# WEBrick is an HTTP server toolkit that can be configured as an HTTPS server,
+# a proxy server, and a virtual-host server.  WEBrick features complete
+# logging of both server operations and HTTP access.  WEBrick supports both
+# basic and digest authentication in addition to algorithms not in RFC 2617.
+#
+# A WEBrick servers can be composed of multiple WEBrick servers or servlets to
+# provide differing behavior on a per-host or per-path basis.  WEBrick
+# includes servlets for handling CGI scripts, ERb pages, ruby blocks and
+# directory listings.
+#
+# WEBrick also includes tools for daemonizing a process and starting a process
+# at a higher privilege level and dropping permissions.
+#
+# == Starting an HTTP server
+#
+# To create a new WEBrick::HTTPServer that will listen to connections on port
+# 8000 and serve documents from the current user's public_html folder:
+#
+#   require 'webrick'
+#
+#   root = File.expand_path '~/public_html'
+#   server = WEBrick::HTTPServer.new :Port => 8000, :DocumentRoot => root
+#
+# To run the server you will need to provide a suitable shutdown hook as
+# starting the server blocks the current thread:
+#
+#   trap 'INT' do server.shutdown end
+#
+#   server.start
+#
+# == Custom Behavior
+#
+# The easiest way to have a server perform custom operations is through
+# WEBrick::HTTPServer#mount_proc.  The block given will be called with a
+# WEBrick::HTTPRequest with request info and a WEBrick::HTTPResponse which
+# must be filled in appropriately:
+#
+#   server.mount_proc '/' do |req, res|
+#     res.body = 'Hello, world!'
+#   end
+#
+# Remember that <tt>server.mount_proc</tt> must <tt>server.start</tt>.
+#
+# == Servlets
+#
+# Advanced custom behavior can be obtained through mounting a subclass of
+# WEBrick::HTTPServlet::AbstractServlet.  Servlets provide more modularity
+# when writing an HTTP server than mount_proc allows.  Here is a simple
+# servlet:
+#
+#   class Simple < WEBrick::HTTPServlet::AbstractServlet
+#     def do_GET request, response
+#       status, content_type, body = do_stuff_with request
+#
+#       response.status = 200
+#       response['Content-Type'] = 'text/plain'
+#       response.body = 'Hello, World!'
+#     end
+#   end
+#
+# To initialize the servlet you mount it on the server:
+#
+#   server.mount '/simple', Simple
+#
+# See WEBrick::HTTPServlet::AbstractServlet for more details.
+#
+# == Virtual Hosts
+#
+# A server can act as a virtual host for multiple host names.  After creating
+# the listening host, additional hosts that do not listen can be created and
+# attached as virtual hosts:
+#
+#   server = WEBrick::HTTPServer.new # ...
+#
+#   vhost = WEBrick::HTTPServer.new :ServerName => 'vhost.example',
+#                                   :DoNotListen => true, # ...
+#   vhost.mount '/', ...
+#
+#   server.virtual_host vhost
+#
+# If no +:DocumentRoot+ is provided and no servlets or procs are mounted on the
+# main server it will return 404 for all URLs.
+#
+# == HTTPS
+#
+# To create an HTTPS server you only need to enable SSL and provide an SSL
+# certificate name:
+#
+#   require 'webrick'
+#   require 'webrick/https'
+#
+#   cert_name = [
+#     %w[CN localhost],
+#   ]
+#
+#   server = WEBrick::HTTPServer.new(:Port => 8000,
+#                                    :SSLEnable => true,
+#                                    :SSLCertName => cert_name)
+#
+# This will start the server with a self-generated self-signed certificate.
+# The certificate will be changed every time the server is restarted.
+#
+# To create a server with a pre-determined key and certificate you can provide
+# them:
+#
+#   require 'webrick'
+#   require 'webrick/https'
+#   require 'openssl'
+#
+#   cert = OpenSSL::X509::Certificate.new File.read '/path/to/cert.pem'
+#   pkey = OpenSSL::PKey::RSA.new File.read '/path/to/pkey.pem'
+#
+#   server = WEBrick::HTTPServer.new(:Port => 8000,
+#                                    :SSLEnable => true,
+#                                    :SSLCertificate => cert,
+#                                    :SSLPrivateKey => pkey)
+#
+# == Proxy Server
+#
+# WEBrick can act as a proxy server:
+#
+#   require 'webrick'
+#   require 'webrick/httpproxy'
+#
+#   proxy = WEBrick::HTTPProxyServer.new :Port => 8000
+#
+#   trap 'INT' do proxy.shutdown end
+#
+# Proxies may modifier the content of the response through the
+# +:ProxyContentHandler+ callback which will be invoked with the request and
+# respone after the remote content has been fetched.
+#
+# == WEBrick as a Production Web Server
+#
+# WEBrick can be run as a production server for small loads.
+#
+# === Daemonizing
+#
+# To start a WEBrick server as a daemon simple run WEBrick::Daemon.start
+# before starting the server.
+#
+# === Dropping Permissions
+#
+# WEBrick can be started as one user to gain permission to bind to port 80 or
+# 443 for serving HTTP or HTTPS traffic then can drop these permissions for
+# regular operation.  To listen on all interfaces for HTTP traffic:
+#
+#   sockets = WEBrick::Utils.create_listeners nil, 80
+#
+# Then drop privileges:
+#
+#   WEBrick::Utils.su 'www'
+#
+# Then create a server that does not listen by default:
+#
+#   server = WEBrick::HTTPServer.new :DoNotListen => true, # ...
+#
+# Then overwrite the listening sockets with the port 80 sockets:
+#
+#   server.listeners.replace sockets
+#
+# === Logging
+#
+# WEBrick can separately log server operations and end-user access.  For
+# server operations:
+#
+#   log_file = File.open '/var/log/webrick.log', 'a+'
+#   log = WEBrick::Log.new log_file
+#
+# For user access logging:
+#
+#   access_log = [
+#     [log_file, WEBrick::AccessLog::COMBINED_LOG_FORMAT],
+#   ]
+#
+#   server = WEBrick::HTTPServer.new :Logger => log, :AccessLog => access_log
+#
+# See WEBrick::AccessLog for further log formats.
+#
+# === Log Rotation
+#
+# To rotate logs in WEBrick on a HUP signal (like syslogd can send), open the
+# log file in 'a+' mode (as above) and trap 'HUP' to reopen the log file:
+#
+#   trap 'HUP' do log_file.reopen '/path/to/webrick.log', 'a+'
+#
+# == Copyright
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
+#
 # Copyright (c) 2000 TAKAHASHI Masayoshi, GOTOU YUUZOU
 # Copyright (c) 2002 Internet Programming with Ruby writers. All rights
 # reserved.
-#
+#--
 # $IPR: webrick.rb,v 1.12 2002/10/01 17:16:31 gotoyuzo Exp $
 
+module WEBrick
+end
+
 require 'webrick/compat.rb'
 
 require 'webrick/version.rb'

lib/webrick/accesslog.rb

@@ -8,21 +8,90 @@
 # $IPR: accesslog.rb,v 1.1 2002/10/01 17:16:32 gotoyuzo Exp $
 
 module WEBrick
+
+  ##
+  # AccessLog provides logging to various files in various formats.
+  #
+  # Multiple logs may be written to at the same time:
+  #
+  #   access_log = [
+  #     [$stderr, WEBrick::AccessLog::COMMON_LOG_FORMAT],
+  #     [$stderr, WEBrick::AccessLog::REFERER_LOG_FORMAT],
+  #   ]
+  #
+  #   server = WEBrick::HTTPServer.new :AccessLog => access_log
+  #
+  # Custom log formats may be defined.  WEBrick::AccessLog provides a subset
+  # of the formatting from Apache's mod_log_config
+  # http://httpd.apache.org/docs/mod/mod_log_config.html#formats.  See
+  # AccessLog::setup_params for a list of supported options
+
   module AccessLog
+
+    ##
+    # Raised if a parameter such as %e, %i, %o or %n is used without fetching
+    # a specific field.
+
     class AccessLogError < StandardError; end
 
+    ##
+    # The Common Log Format's time format
+
     CLF_TIME_FORMAT     = "[%d/%b/%Y:%H:%M:%S %Z]"
+
+    ##
+    # Common Log Format
+
     COMMON_LOG_FORMAT   = "%h %l %u %t \"%r\" %s %b"
+
+    ##
+    # Short alias for Common Log Format
+
     CLF                 = COMMON_LOG_FORMAT
+
+    ##
+    # Referer Log Format
+
     REFERER_LOG_FORMAT  = "%{Referer}i -> %U"
+
+    ##
+    # User-Agent Log Format
+
     AGENT_LOG_FORMAT    = "%{User-Agent}i"
+
+    ##
+    # Combined Log Format
+
     COMBINED_LOG_FORMAT = "#{CLF} \"%{Referer}i\" \"%{User-agent}i\""
 
     module_function
 
-    # This format specification is a subset of mod_log_config of Apache.
-    #   http://httpd.apache.org/docs/mod/mod_log_config.html#formats
-    def setup_params(config, req, res)
+    # This format specification is a subset of mod_log_config of Apache:
+    #
+    # %a:: Remote IP address
+    # %b:: Total response size
+    # %e{variable}:: Given variable in ENV
+    # %f:: Response filename
+    # %h:: Remote host name
+    # %{header}i:: Given request header
+    # %l:: Remote logname, always "-"
+    # %m:: Request method
+    # %{attr}n:: Given request attribute from <tt>req.attributes</tt>
+    # %{header}o:: Given response header
+    # %p:: Server's request port
+    # %{format}p:: The canonical port of the server serving the request or the
+    #              actual port or the client's actual port.  Valid formats are
+    #              canonical, local or remote.
+    # %q:: Request query string
+    # %r:: First line of the request
+    # %s:: Request status
+    # %t:: Time the request was recieved
+    # %T:: Time taken to process the request
+    # %u:: Remote user from auth
+    # %U:: Unparsed URI
+    # %%:: Literal %
+
+     def setup_params(config, req, res)
       params = Hash.new("")
       params["a"] = req.peeraddr[3]
       params["b"] = res.sent_size

lib/webrick/htmlutils.rb

@@ -11,6 +11,9 @@
 module WEBrick
   module HTMLUtils
 
+    ##
+    # Escapes &, ", > and < in +string+
+
     def escape(string)
       str = string ? string.dup : ""
       str.gsub!(/&/n, '&amp;')

lib/webrick/httpproxy.rb

@@ -33,7 +33,24 @@ def method_missing(meth, *args)
     end
   end
 
+  ##
+  # An HTTP Proxy server which proxies GET, HEAD and POST requests.
+
   class HTTPProxyServer < HTTPServer
+
+    ##
+    # Proxy server configurations.  The proxy server handles the following
+    # configuration items in addition to those supported by HTTPServer:
+    #
+    # :ProxyAuthProc:: Called with a request and response to authorize a
+    #                  request
+    # :ProxyVia:: Appended to the via header
+    # :ProxyURI:: The proxy server's URI
+    # :ProxyContentHandler:: Called with a request and resopnse and allows
+    #                        modification of the response
+    # :ProxyTimeout:: Sets the proxy timeouts to 30 seconds for open and 60
+    #                 seconds for read operations
+
     def initialize(config={}, default=Config::HTTP)
       super(config, default)
       c = @config