1##
2# = WEB server toolkit.
3#
4# WEBrick is an HTTP server toolkit that can be configured as an HTTPS server,
5# a proxy server, and a virtual-host server.  WEBrick features complete
6# logging of both server operations and HTTP access.  WEBrick supports both
7# basic and digest authentication in addition to algorithms not in RFC 2617.
8#
9# A WEBrick server can be composed of multiple WEBrick servers or servlets to
10# provide differing behavior on a per-host or per-path basis.  WEBrick
11# includes servlets for handling CGI scripts, ERb pages, ruby blocks and
12# directory listings.
13#
14# WEBrick also includes tools for daemonizing a process and starting a process
15# at a higher privilege level and dropping permissions.
16#
17# == Starting an HTTP server
18#
19# To create a new WEBrick::HTTPServer that will listen to connections on port
20# 8000 and serve documents from the current user's public_html folder:
21#
22#   require 'webrick'
23#
24#   root = File.expand_path '~/public_html'
25#   server = WEBrick::HTTPServer.new :Port => 8000, :DocumentRoot => root
26#
27# To run the server you will need to provide a suitable shutdown hook as
28# starting the server blocks the current thread:
29#
30#   trap 'INT' do server.shutdown end
31#
32#   server.start
33#
34# == Custom Behavior
35#
36# The easiest way to have a server perform custom operations is through
37# WEBrick::HTTPServer#mount_proc.  The block given will be called with a
38# WEBrick::HTTPRequest with request info and a WEBrick::HTTPResponse which
39# must be filled in appropriately:
40#
41#   server.mount_proc '/' do |req, res|
42#     res.body = 'Hello, world!'
43#   end
44#
45# Remember that <tt>server.mount_proc</tt> must <tt>server.start</tt>.
46#
47# == Servlets
48#
49# Advanced custom behavior can be obtained through mounting a subclass of
50# WEBrick::HTTPServlet::AbstractServlet.  Servlets provide more modularity
51# when writing an HTTP server than mount_proc allows.  Here is a simple
52# servlet:
53#
54#   class Simple < WEBrick::HTTPServlet::AbstractServlet
55#     def do_GET request, response
56#       status, content_type, body = do_stuff_with request
57#
58#       response.status = 200
59#       response['Content-Type'] = 'text/plain'
60#       response.body = 'Hello, World!'
61#     end
62#   end
63#
64# To initialize the servlet you mount it on the server:
65#
66#   server.mount '/simple', Simple
67#
68# See WEBrick::HTTPServlet::AbstractServlet for more details.
69#
70# == Virtual Hosts
71#
72# A server can act as a virtual host for multiple host names.  After creating
73# the listening host, additional hosts that do not listen can be created and
74# attached as virtual hosts:
75#
76#   server = WEBrick::HTTPServer.new # ...
77#
78#   vhost = WEBrick::HTTPServer.new :ServerName => 'vhost.example',
79#                                   :DoNotListen => true, # ...
80#   vhost.mount '/', ...
81#
82#   server.virtual_host vhost
83#
84# If no +:DocumentRoot+ is provided and no servlets or procs are mounted on the
85# main server it will return 404 for all URLs.
86#
87# == HTTPS
88#
89# To create an HTTPS server you only need to enable SSL and provide an SSL
90# certificate name:
91#
92#   require 'webrick'
93#   require 'webrick/https'
94#
95#   cert_name = [
96#     %w[CN localhost],
97#   ]
98#
99#   server = WEBrick::HTTPServer.new(:Port => 8000,
100#                                    :SSLEnable => true,
101#                                    :SSLCertName => cert_name)
102#
103# This will start the server with a self-generated self-signed certificate.
104# The certificate will be changed every time the server is restarted.
105#
106# To create a server with a pre-determined key and certificate you can provide
107# them:
108#
109#   require 'webrick'
110#   require 'webrick/https'
111#   require 'openssl'
112#
113#   cert = OpenSSL::X509::Certificate.new File.read '/path/to/cert.pem'
114#   pkey = OpenSSL::PKey::RSA.new File.read '/path/to/pkey.pem'
115#
116#   server = WEBrick::HTTPServer.new(:Port => 8000,
117#                                    :SSLEnable => true,
118#                                    :SSLCertificate => cert,
119#                                    :SSLPrivateKey => pkey)
120#
121# == Proxy Server
122#
123# WEBrick can act as a proxy server:
124#
125#   require 'webrick'
126#   require 'webrick/httpproxy'
127#
128#   proxy = WEBrick::HTTPProxyServer.new :Port => 8000
129#
130#   trap 'INT' do proxy.shutdown end
131#
132# See WEBrick::HTTPProxy for further details including modifying proxied
133# responses.
134#
135# == Basic and Digest authentication
136#
137# WEBrick provides both Basic and Digest authentication for regular and proxy
138# servers.  See WEBrick::HTTPAuth, WEBrick::HTTPAuth::BasicAuth and
139# WEBrick::HTTPAuth::DigestAuth.
140#
141# == WEBrick as a Production Web Server
142#
143# WEBrick can be run as a production server for small loads.
144#
145# === Daemonizing
146#
147# To start a WEBrick server as a daemon simple run WEBrick::Daemon.start
148# before starting the server.
149#
150# === Dropping Permissions
151#
152# WEBrick can be started as one user to gain permission to bind to port 80 or
153# 443 for serving HTTP or HTTPS traffic then can drop these permissions for
154# regular operation.  To listen on all interfaces for HTTP traffic:
155#
156#   sockets = WEBrick::Utils.create_listeners nil, 80
157#
158# Then drop privileges:
159#
160#   WEBrick::Utils.su 'www'
161#
162# Then create a server that does not listen by default:
163#
164#   server = WEBrick::HTTPServer.new :DoNotListen => true, # ...
165#
166# Then overwrite the listening sockets with the port 80 sockets:
167#
168#   server.listeners.replace sockets
169#
170# === Logging
171#
172# WEBrick can separately log server operations and end-user access.  For
173# server operations:
174#
175#   log_file = File.open '/var/log/webrick.log', 'a+'
176#   log = WEBrick::Log.new log_file
177#
178# For user access logging:
179#
180#   access_log = [
181#     [log_file, WEBrick::AccessLog::COMBINED_LOG_FORMAT],
182#   ]
183#
184#   server = WEBrick::HTTPServer.new :Logger => log, :AccessLog => access_log
185#
186# See WEBrick::AccessLog for further log formats.
187#
188# === Log Rotation
189#
190# To rotate logs in WEBrick on a HUP signal (like syslogd can send), open the
191# log file in 'a+' mode (as above) and trap 'HUP' to reopen the log file:
192#
193#   trap 'HUP' do log_file.reopen '/path/to/webrick.log', 'a+'
194#
195# == Copyright
196#
197# Author: IPR -- Internet Programming with Ruby -- writers
198#
199# Copyright (c) 2000 TAKAHASHI Masayoshi, GOTOU YUUZOU
200# Copyright (c) 2002 Internet Programming with Ruby writers. All rights
201# reserved.
202#--
203# $IPR: webrick.rb,v 1.12 2002/10/01 17:16:31 gotoyuzo Exp $
204
205module WEBrick
206end
207
208require 'webrick/compat.rb'
209
210require 'webrick/version.rb'
211require 'webrick/config.rb'
212require 'webrick/log.rb'
213require 'webrick/server.rb'
214require 'webrick/utils.rb'
215require 'webrick/accesslog'
216
217require 'webrick/htmlutils.rb'
218require 'webrick/httputils.rb'
219require 'webrick/cookie.rb'
220require 'webrick/httpversion.rb'
221require 'webrick/httpstatus.rb'
222require 'webrick/httprequest.rb'
223require 'webrick/httpresponse.rb'
224require 'webrick/httpserver.rb'
225require 'webrick/httpservlet.rb'
226require 'webrick/httpauth.rb'
227