rubysl-webrick 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: d8994245d4c318c3596b0c96a9608c372d0fd7fd
-  data.tar.gz: 4741b54181f8e4ace05485f7985d1fcc3e3fd28e
-SHA512:
-  metadata.gz: 9f294bfa3fe38668ae4bc1d5a82ddde945038cb1823e3f1f7dceb6ceb16c5afc8bdc74dcfa63d2fea181dc2c51e38de468c85e676187380dc3f472f0ae900158
-  data.tar.gz: 747dcf8e42c579a4cf766167e5b56a7d58160277b0f48a889c40f82d175ecae054ed83275d8870a01d956c95f3574865924bf85923511f958b19243e36928019
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTkyOGI2NzczYTNjMTlmYjI2YTdjNmM2ZDRlYjc4ODZhZTY5NTUwMg==
+  data.tar.gz: !binary |-
+    NGViN2JmMzdiZDNiMjM5OTM5Mzg4YzY2OWJlZjg4NmUzYmMzOTJkOA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NWM4MmVkNzFiM2RiNDVkNTY2MjBjNzkxYzNhZDNkOGVjOWViNTkxNjg5YmU1
+    NjVlOTViNDk0M2RhMDMwYjJiZTY5YWJjM2Y4OWI3NWQ4ODExMzlmOTYxZjYx
+    OGFkNTE3YjM1MDU4YTdmOWFjYjFmNDkwMjJkMTI3OTM1MmE0OGM=
+  data.tar.gz: !binary |-
+    YTNkNjVlZDA0YTQxOTUyMWJlNmQwMWY4NTA1NzI4ZTA5MjY2N2RmY2QyN2Vl
+    YTAyODUwYjliYjliNjYwOWVlMTQyNWZmZDI3NzhmZTE2NDViYTZkYjM2ODZm
+    ZTgwMzdmMTc1ODEyZDRkMTMzMmEzMjA5MGIzMGExNmYxZmM4NDk=

data/.travis.yml

@@ -1,8 +1,7 @@
 language: ruby
-before_install:
-  - gem update --system
-  - gem --version
-  - gem install rubysl-bundler
-script: bundle exec mspec spec
+env:
+  - RUBYLIB=lib
+script: bundle exec mspec
 rvm:
-  - rbx-nightly-18mode
+  - 1.9.3
+  - rbx-nightly-19mode

data/lib/rubysl/webrick/version.rb

@@ -1,5 +1,5 @@
 module RubySL
   module WEBrick
-    VERSION = "1.0.0"
+    VERSION = "2.0.0"
   end
 end

data/lib/rubysl/webrick/webrick.rb

@@ -1,13 +1,210 @@
+##
+# = 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 server 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
+#
+# See WEBrick::HTTPProxy for further details including modifying proxied
+# responses.
+#
+# == Basic and Digest authentication
+#
+# WEBrick provides both Basic and Digest authentication for regular and proxy
+# servers.  See WEBrick::HTTPAuth, WEBrick::HTTPAuth::BasicAuth and
+# WEBrick::HTTPAuth::DigestAuth.
+#
+# == 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'

data/lib/webrick/accesslog.rb

@@ -1,4 +1,4 @@
-#
+#--
 # accesslog.rb -- Access log handling utilities
 #
 # Author: IPR -- Internet Programming with Ruby -- writers
@@ -8,20 +8,89 @@
 # $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
+    # 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]
@@ -46,6 +115,10 @@ module WEBrick
       params
     end
 
+    ##
+    # Formats +params+ according to +format_string+ which is described in
+    # setup_params.
+
     def format(format_string, params)
       format_string.gsub(/\%(?:\{(.*?)\})?>?([a-zA-Z%])/){
          param, spec = $1, $2
@@ -53,15 +126,33 @@ module WEBrick
          when ?e, ?i, ?n, ?o
            raise AccessLogError,
              "parameter is required for \"#{spec}\"" unless param
-           params[spec][param] || "-"
+           (param = params[spec][param]) ? escape(param) : "-"
          when ?t
            params[spec].strftime(param || CLF_TIME_FORMAT)
+         when ?p
+           case param
+           when 'remote'
+             escape(params["i"].peeraddr[1].to_s)
+           else
+             escape(params["p"].to_s)
+           end
          when ?%
            "%"
          else
-           params[spec]
+           escape(params[spec].to_s)
          end
       }
     end
+
+    ##
+    # Escapes control characters in +data+
+
+    def escape(data)
+      if data.tainted?
+        data.gsub(/[[:cntrl:]\\]+/) {$&.dump[1...-1]}.untaint
+      else
+        data
+      end
+    end
   end
 end

data/lib/webrick/cgi.rb

@@ -5,7 +5,7 @@
 # Copyright (c) 2003 Internet Programming with Ruby writers. All rights
 # reserved.
 #
-# $Id: cgi.rb 11708 2007-02-12 23:01:19Z shyouhei $
+# $Id$
 
 require "webrick/httprequest"
 require "webrick/httpresponse"
@@ -13,10 +13,44 @@ require "webrick/config"
 require "stringio"
 
 module WEBrick
+
+  # A CGI library using WEBrick requests and responses.
+  #
+  # Example:
+  #
+  #   class MyCGI < WEBrick::CGI
+  #     def do_GET req, res
+  #       res.body = 'it worked!'
+  #       res.status = 200
+  #     end
+  #   end
+  #
+  #   MyCGI.new.start
+
   class CGI
+
+    # The CGI error exception class
+
     CGIError = Class.new(StandardError)
 
-    attr_reader :config, :logger
+    ##
+    # The CGI configuration.  This is based on WEBrick::Config::HTTP
+
+    attr_reader :config
+
+    ##
+    # The CGI logger
+
+    attr_reader :logger
+
+    ##
+    # Creates a new CGI interface.
+    #
+    # The first argument in +args+ is a configuration hash which would update
+    # WEBrick::Config::HTTP.
+    #
+    # Any remaining arguments are stored in the <code>@options</code> instance
+    # variable for use by a subclass.
 
     def initialize(*args)
       if defined?(MOD_RUBY)
@@ -41,10 +75,17 @@ module WEBrick
       @options = args
     end
 
+    ##
+    # Reads +key+ from the configuration
+
     def [](key)
       @config[key]
     end
 
+    ##
+    # Starts the CGI process with the given environment +env+ and standard
+    # input and output +stdin+ and +stdout+.
+
     def start(env=ENV, stdin=$stdin, stdout=$stdout)
       sock = WEBrick::CGI::Socket.new(@config, env, stdin, stdout)
       req = HTTPRequest.new(@config)
@@ -77,7 +118,7 @@ module WEBrick
         res.set_error(ex)
       rescue HTTPStatus::Status => ex
         res.status = ex.code
-      rescue Exception => ex 
+      rescue Exception => ex
         @logger.error(ex)
         res.set_error(ex, true)
       ensure
@@ -108,6 +149,10 @@ module WEBrick
       end
     end
 
+    ##
+    # Services the request +req+ which will fill in the response +res+.  See
+    # WEBrick::HTTPServlet::AbstractServlet#service for details.
+
     def service(req, res)
       method_name = "do_" + req.request_method.gsub(/-/, "_")
       if respond_to?(method_name)
@@ -118,11 +163,14 @@ module WEBrick
       end
     end
 
-    class Socket
+    ##
+    # Provides HTTP socket emulation from the CGI environment
+
+    class Socket # :nodoc:
       include Enumerable
 
       private
-  
+
       def initialize(config, env, stdin, stdout)
         @config = config
         @env = env
@@ -130,7 +178,7 @@ module WEBrick
         @body_part = stdin
         @out_port = stdout
         @out_port.binmode
-  
+
         @server_addr = @env["SERVER_ADDR"] || "0.0.0.0"
         @server_name = @env["SERVER_NAME"]
         @server_port = @env["SERVER_PORT"]
@@ -143,7 +191,7 @@ module WEBrick
           setup_header
           @header_part << CRLF
           @header_part.rewind
-        rescue Exception => ex
+        rescue Exception
           raise CGIError, "invalid CGI environment"
         end
       end
@@ -164,43 +212,42 @@ module WEBrick
         httpv = @config[:HTTPVersion]
         return "#{meth} #{url} HTTP/#{httpv}"
       end
-  
+
       def setup_header
-        add_header("CONTENT_TYPE", "Content-Type")
-        add_header("CONTENT_LENGTH", "Content-length")
-        @env.each_key{|name|
-          if /^HTTP_(.*)/ =~ name
-            add_header(name, $1.gsub(/_/, "-"))
+        @env.each{|key, value|
+          case key
+          when "CONTENT_TYPE", "CONTENT_LENGTH"
+            add_header(key.gsub(/_/, "-"), value)
+          when /^HTTP_(.*)/
+            add_header($1.gsub(/_/, "-"), value)
           end
         }
       end
-  
-      def add_header(envname, hdrname)
-        if value = @env[envname]
-          unless value.empty?
-            @header_part << hdrname << ": " << value << CRLF
-          end
+
+      def add_header(hdrname, value)
+        unless value.empty?
+          @header_part << hdrname << ": " << value << CRLF
         end
       end
 
       def input
         @header_part.eof? ? @body_part : @header_part
       end
-  
+
       public
-  
+
       def peeraddr
         [nil, @remote_port, @remote_host, @remote_addr]
       end
-  
+
       def addr
         [nil, @server_port, @server_name, @server_addr]
       end
-  
-      def gets(eol=LF)
-        input.gets(eol)
+
+      def gets(eol=LF, size=nil)
+        input.gets(eol, size)
       end
-  
+
       def read(size=nil)
         input.read(size)
       end
@@ -208,7 +255,11 @@ module WEBrick
       def each
         input.each{|line| yield(line) }
       end
-  
+
+      def eof?
+        input.eof?
+      end
+
       def <<(data)
         @out_port << data
       end
@@ -253,5 +304,5 @@ module WEBrick
         end
       end
     end
-  end 
-end  
+  end
+end