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