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