Skip to content

Commit

Permalink
* lib/webrick: Add Documentation
Browse files Browse the repository at this point in the history
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31499 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information
drbrain committed May 10, 2011
1 parent 7e3ec1d commit 071a678
Show file tree
Hide file tree
Showing 12 changed files with 591 additions and 18 deletions.
4 changes: 4 additions & 0 deletions ChangeLog
Original file line number Diff line number Diff line change
@@ -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
Expand Down
196 changes: 194 additions & 2 deletions lib/webrick.rb
Original file line number Diff line number Diff line change
@@ -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'
Expand Down
75 changes: 72 additions & 3 deletions lib/webrick/accesslog.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions lib/webrick/htmlutils.rb
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@
module WEBrick
module HTMLUtils

##
# Escapes &, ", > and < in +string+

def escape(string)
str = string ? string.dup : ""
str.gsub!(/&/n, '&amp;')
Expand Down
17 changes: 17 additions & 0 deletions lib/webrick/httpproxy.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 071a678

Please sign in to comment.