ruby-changes:26893
From: drbrain <ko1@a...>
Date: Sat, 26 Jan 2013 10:13:11 +0900 (JST)
Subject: [ruby-changes:26893] drbrain:r38945 (trunk): * lib/webrick/accesslog.rb: Improved WEBrick documentation.
drbrain 2013-01-26 10:12:54 +0900 (Sat, 26 Jan 2013) New Revision: 38945 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38945 Log: * lib/webrick/accesslog.rb: Improved WEBrick documentation. * lib/webrick/cgi.rb: ditto. * lib/webrick/config.rb: ditto. * lib/webrick/cookie.rb: ditto. * lib/webrick/httpauth/authenticator.rb: ditto. * lib/webrick/httpauth/basicauth.rb: ditto. * lib/webrick/httpauth/digestauth.rb: ditto. * lib/webrick/httpproxy.rb: ditto. * lib/webrick/httprequest.rb: ditto. * lib/webrick/httpresponse.rb: ditto. * lib/webrick/https.rb: ditto. * lib/webrick/httpserver.rb: ditto. * lib/webrick/httpservlet/cgihandler.rb: ditto. * lib/webrick/httpservlet/filehandler.rb: ditto. * lib/webrick/httpservlet/prochandler.rb: ditto. * lib/webrick/httputils.rb: ditto. * lib/webrick/httpversion.rb: ditto. * lib/webrick/log.rb: ditto. * lib/webrick/server.rb: ditto. * lib/webrick/ssl.rb: ditto. * lib/webrick/utils.rb: ditto. * lib/webrick/version.rb: ditto. Modified files: trunk/ChangeLog trunk/lib/webrick/accesslog.rb trunk/lib/webrick/cgi.rb trunk/lib/webrick/config.rb trunk/lib/webrick/cookie.rb trunk/lib/webrick/httpauth/authenticator.rb trunk/lib/webrick/httpauth/basicauth.rb trunk/lib/webrick/httpauth/digestauth.rb trunk/lib/webrick/httpproxy.rb trunk/lib/webrick/httprequest.rb trunk/lib/webrick/httpresponse.rb trunk/lib/webrick/https.rb trunk/lib/webrick/httpserver.rb trunk/lib/webrick/httpservlet/cgihandler.rb trunk/lib/webrick/httpservlet/filehandler.rb trunk/lib/webrick/httpservlet/prochandler.rb trunk/lib/webrick/httputils.rb trunk/lib/webrick/httpversion.rb trunk/lib/webrick/log.rb trunk/lib/webrick/server.rb trunk/lib/webrick/ssl.rb trunk/lib/webrick/utils.rb trunk/lib/webrick/version.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 38944) +++ ChangeLog (revision 38945) @@ -1,3 +1,28 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Sat Jan 26 10:09:57 2013 Eric Hodel <drbrain@s...> + + * lib/webrick/accesslog.rb: Improved WEBrick documentation. + * lib/webrick/cgi.rb: ditto. + * lib/webrick/config.rb: ditto. + * lib/webrick/cookie.rb: ditto. + * lib/webrick/httpauth/authenticator.rb: ditto. + * lib/webrick/httpauth/basicauth.rb: ditto. + * lib/webrick/httpauth/digestauth.rb: ditto. + * lib/webrick/httpproxy.rb: ditto. + * lib/webrick/httprequest.rb: ditto. + * lib/webrick/httpresponse.rb: ditto. + * lib/webrick/https.rb: ditto. + * lib/webrick/httpserver.rb: ditto. + * lib/webrick/httpservlet/cgihandler.rb: ditto. + * lib/webrick/httpservlet/filehandler.rb: ditto. + * lib/webrick/httpservlet/prochandler.rb: ditto. + * lib/webrick/httputils.rb: ditto. + * lib/webrick/httpversion.rb: ditto. + * lib/webrick/log.rb: ditto. + * lib/webrick/server.rb: ditto. + * lib/webrick/ssl.rb: ditto. + * lib/webrick/utils.rb: ditto. + * lib/webrick/version.rb: ditto. + Sat Jan 26 08:29:33 2013 Shugo Maeda <shugo@r...> * ext/socket/raddrinfo (rsock_unix_sockaddr_len): renamed from Index: lib/webrick/log.rb =================================================================== --- lib/webrick/log.rb (revision 38944) +++ lib/webrick/log.rb (revision 38945) @@ -14,8 +14,27 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/log.rb#L14 # A generic logging class class BasicLog - # log-level constants - FATAL, ERROR, WARN, INFO, DEBUG = 1, 2, 3, 4, 5 + + # Fatal log level which indicates a server crash + + FATAL = 1 + + # Error log level which indicates a recoverable error + + ERROR = 2 + + # Warning log level which indicates a possible problem + + WARN = 3 + + # Information log level which indicates possibly useful information + + INFO = 4 + + # Debugging error level for messages used in server development or + # debugging + + DEBUG = 5 # log-level, messages above this level will be logged attr_accessor :level Index: lib/webrick/httpproxy.rb =================================================================== --- lib/webrick/httpproxy.rb (revision 38944) +++ lib/webrick/httpproxy.rb (revision 38945) @@ -15,16 +15,17 @@ require "net/http" https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpproxy.rb#L15 Net::HTTP::version_1_2 if RUBY_VERSION < "1.7" module WEBrick - NullReader = Object.new - class << NullReader + + NullReader = Object.new # :nodoc: + class << NullReader # :nodoc: def read(*args) nil end alias gets read end - FakeProxyURI = Object.new - class << FakeProxyURI + FakeProxyURI = Object.new # :nodoc: + class << FakeProxyURI # :nodoc: def method_missing(meth, *args) if %w(scheme host port path query userinfo).member?(meth.to_s) return nil @@ -33,6 +34,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpproxy.rb#L34 end end + # :startdoc: + ## # An HTTP Proxy server which proxies GET, HEAD and POST requests. # @@ -85,6 +88,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpproxy.rb#L88 @via = "#{c[:HTTPVersion]} #{c[:ServerName]}:#{c[:Port]}" end + # :stopdoc: def service(req, res) if req.request_method == "CONNECT" do_CONNECT(req, res) @@ -329,5 +333,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpproxy.rb#L333 set_via(res) res.body = response.body end + + # :stopdoc: end end Index: lib/webrick/httpservlet/filehandler.rb =================================================================== --- lib/webrick/httpservlet/filehandler.rb (revision 38944) +++ lib/webrick/httpservlet/filehandler.rb (revision 38945) @@ -18,12 +18,29 @@ require 'webrick/httpstatus' https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/filehandler.rb#L18 module WEBrick module HTTPServlet + ## + # Servlet for serving a single file. You probably want to use the + # FileHandler servlet instead as it handles directories and fancy indexes. + # + # Example: + # + # server.mount('/my_page.txt', WEBrick::HTTPServlet::DefaultFileHandler, + # '/path/to/my_page.txt') + # + # This servlet handles If-Modified-Since and Range requests. + class DefaultFileHandler < AbstractServlet + + ## + # Creates a DefaultFileHandler instance for the file at +local_path+. + def initialize(server, local_path) super(server, local_path) @local_path = local_path end + # :stopdoc: + def do_GET(req, res) st = File::stat(@local_path) mtime = st.mtime @@ -123,13 +140,20 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/filehandler.rb#L140 last = filesize - 1 if last >= filesize return first, last end + + # :startdoc: end ## - # Serves files from a directory + # Serves a directory including fancy indexing and a variety of other + # options. + # + # Example: + # + # server.mount '/assets', WEBrick::FileHandler, '/path/to/assets' class FileHandler < AbstractServlet - HandlerTable = Hash.new + HandlerTable = Hash.new # :nodoc: ## # Allow custom handling of requests for files with +suffix+ by class @@ -150,19 +174,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/filehandler.rb#L174 # Creates a FileHandler servlet on +server+ that serves files starting # at directory +root+ # - # If +options+ is a Hash the following keys are allowed: - # - # :AcceptableLanguages:: Array of languages allowed for accept-language - # :DirectoryCallback:: Allows preprocessing of directory requests - # :FancyIndexing:: If true, show an index for directories - # :FileCallback:: Allows preprocessing of file requests - # :HandlerCallback:: Allows preprocessing of requests - # :HandlerTable:: Maps file suffixes to file handlers. - # DefaultFileHandler is used by default but any servlet - # can be used. - # :NondisclosureName:: Do not show files matching this array of globs - # :UserDir:: Directory inside ~user to serve content from for /~user - # requests. Only works if mounted on / + # +options+ may be a Hash containing keys from + # WEBrick::Config::FileHandler or +true+ or +false+. # # If +options+ is true or false then +:FancyIndexing+ is enabled or # disabled respectively. @@ -177,6 +190,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/filehandler.rb#L190 @options = default.dup.update(options) end + # :stopdoc: + def service(req, res) # if this class is mounted on "/" and /~username is requested. # we're going to override path informations before invoking service. @@ -465,6 +480,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/filehandler.rb#L480 _end_of_html_ end + # :startdoc: end end end Index: lib/webrick/httpservlet/cgihandler.rb =================================================================== --- lib/webrick/httpservlet/cgihandler.rb (revision 38944) +++ lib/webrick/httpservlet/cgihandler.rb (revision 38945) @@ -16,9 +16,20 @@ require 'webrick/httpservlet/abstract' https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/cgihandler.rb#L16 module WEBrick module HTTPServlet + ## + # Servlet for handling CGI scripts + # + # Example: + # + # server.mount('/cgi/my_script', WEBrick::HTTPServlet::CGIHandler, + # '/path/to/my_script') + class CGIHandler < AbstractServlet - Ruby = RbConfig.ruby - CGIRunner = "\"#{Ruby}\" \"#{WEBrick::Config::LIBDIR}/httpservlet/cgi_runner.rb\"" + Ruby = RbConfig.ruby # :nodoc: + CGIRunner = "\"#{Ruby}\" \"#{WEBrick::Config::LIBDIR}/httpservlet/cgi_runner.rb\"" # :nodoc: + + ## + # Creates a new CGI script servlet for the script at +name+ def initialize(server, name) super(server, name) @@ -27,6 +38,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/cgihandler.rb#L38 @cgicmd = "#{CGIRunner} #{server[:CGIInterpreter]}" end + # :stopdoc: + def do_GET(req, res) data = nil status = -1 @@ -102,6 +115,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/cgihandler.rb#L115 res.body = body end alias do_POST do_GET + + # :startdoc: end end Index: lib/webrick/httpservlet/prochandler.rb =================================================================== --- lib/webrick/httpservlet/prochandler.rb (revision 38944) +++ lib/webrick/httpservlet/prochandler.rb (revision 38945) @@ -13,7 +13,19 @@ require 'webrick/httpservlet/abstract.rb https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/prochandler.rb#L13 module WEBrick module HTTPServlet + ## + # Mounts a proc at a path that accepts a request and response. + # + # Instead of mounting this servlet with WEBrick::HTTPServer#mount use + # WEBrick::HTTPServer#mount_proc: + # + # server.mount_proc '/' do |req, res| + # res.body = 'it worked!' + # res.status = 200 + # end + class ProcHandler < AbstractServlet + # :stopdoc: def get_instance(server, *options) self end @@ -27,6 +39,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpservlet/prochandler.rb#L39 end alias do_POST do_GET + # :startdoc: end end Index: lib/webrick/version.rb =================================================================== --- lib/webrick/version.rb (revision 38944) +++ lib/webrick/version.rb (revision 38945) @@ -9,5 +9,9 @@ https://github.com/ruby/ruby/blob/trunk/lib/webrick/version.rb#L9 # $IPR: version.rb,v 1.74 2003/07/22 19:20:43 gotoyuzo Exp $ module WEBrick + + ## + # The WEBrick version + VERSION = "1.3.1" end Index: lib/webrick/httpversion.rb =================================================================== --- lib/webrick/httpversion.rb (revision 38944) +++ lib/webrick/httpversion.rb (revision 38945) @@ -8,15 +8,33 @@ https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpversion.rb#L8 # $IPR: httpversion.rb,v 1.5 2002/09/21 12:23:37 gotoyuzo Exp $ module WEBrick + + ## + # Represents an HTTP protocol version + class HTTPVersion include Comparable - attr_accessor :major, :minor + ## + # The major protocol version number + + attr_accessor :major + + ## + # The minor protocol version number + + attr_accessor :minor + + ## + # Converts +version+ into an HTTPVersion def self.convert(version) version.is_a?(self) ? version : new(version) end + ## + # Creates a new HTTPVersion from +version+. + def initialize(version) case version when HTTPVersion @@ -32,6 +50,10 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpversion.rb#L50 end end + ## + # Compares this version with +other+ according to the HTTP specification + # rules. + def <=>(other) unless other.is_a?(self.class) other = self.class.new(other) @@ -42,6 +64,10 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpversion.rb#L64 return ret end + ## + # The HTTP version as show in the HTTP request and response. For example, + # "1.1" + def to_s format("%d.%d", @major, @minor) end Index: lib/webrick/httprequest.rb =================================================================== --- lib/webrick/httprequest.rb (revision 38944) +++ lib/webrick/httprequest.rb (revision 38945) @@ -17,31 +17,137 @@ require 'webrick/cookie' https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L17 module WEBrick ## - # An HTTP request. + # An HTTP request. This is consumed by service and do_* methods in + # WEBrick servlets + class HTTPRequest - BODY_CONTAINABLE_METHODS = [ "POST", "PUT" ] + BODY_CONTAINABLE_METHODS = [ "POST", "PUT" ] # :nodoc: # :section: Request line + + ## + # The complete request line such as: + # + # GET / HTTP/1.1 + attr_reader :request_line - attr_reader :request_method, :unparsed_uri, :http_version + + ## + # The request method, GET, POST, PUT, etc. + + attr_reader :request_method + + ## + # The unparsed URI of the request + + attr_reader :unparsed_uri + + ## + # The HTTP version of the request + + attr_reader :http_version # :section: Request-URI - attr_reader :request_uri, :path - attr_accessor :script_name, :path_info, :query_string + + ## + # The parsed URI of the request + + attr_reader :request_uri + + ## + # The request path + + attr_reader :path + + ## + # The script name (CGI variable) + + attr_accessor :script_name + + ## + # The path info (CGI variable) + + attr_accessor :path_info + + ## + # The query from the URI of the request + + attr_accessor :query_string # :section: Header and entity body - attr_reader :raw_header, :header, :cookies - attr_reader :accept, :accept_charset - attr_reader :accept_encoding, :accept_language + + ## + # The raw header of the request + + attr_reader :raw_header + + ## + # The parsed header of the request + + attr_reader :header + + ## + # The parsed request cookies + + attr_reader :cookies + + ## + # The Accept header value + + attr_reader :accept + + ## + # The Accept-Charset header value + + attr_reader :accept_charset + + ## + # The Accept-Encoding header value + + attr_reader :accept_encoding + + ## + # The Accept-Language header value + + attr_reader :accept_language # :section: + + ## + # The remote user (CGI variable) + attr_accessor :user - attr_reader :addr, :peeraddr + + ## + # The socket address of the server + + attr_reader :addr + + ## + # The socket address of the client + + attr_reader :peeraddr + + ## + # Hash of request attributes + attr_reader :attributes + + ## + # Is this a keep-alive connection? + attr_reader :keep_alive + + ## + # The local time this request was received + attr_reader :request_time + ## + # Creates a new HTTP request. WEBrick::Config::HTTP is the default + # configuration. + def initialize(config) @config = config @buffer_size = @config[:InputBufferSize] @@ -78,6 +184,10 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L184 @forwarded_server = @forwarded_for = nil end + ## + # Parses a request from +socket+. This is called internally by + # WEBrick::HTTPServer. + def parse(socket=nil) @socket = socket begin @@ -126,16 +236,21 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L236 end end + ## # Generate HTTP/1.1 100 continue response if the client expects it, # otherwise does nothing. - def continue + + def continue # :nodoc: if self['expect'] == '100-continue' && @config[:HTTPVersion] >= "1.1" @socket << "HTTP/#{@config[:HTTPVersion]} 100 continue#{CRLF}#{CRLF}" @header.delete('expect') end end - def body(&block) + ## + # Returns the request body. + + def body(&block) # :yields: body_chunk block ||= Proc.new{|chunk| @body << chunk } read_body(@socket, block) @body.empty? ? nil : @body @@ -237,7 +352,10 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L352 ret end - def fixup() + ## + # Consumes any remaining body and updates keep-alive status + + def fixup() # :nodoc: begin body{|chunk| } # read remaining body rescue HTTPStatus::Error => ex @@ -290,6 +408,8 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L408 private + # :stopdoc: + MAX_URI_LENGTH = 2083 # :nodoc: def read_request_line(socket) @@ -457,5 +577,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httprequest.rb#L577 @forwarded_for = addrs.first end end + + # :startdoc: end end Index: lib/webrick/httpresponse.rb =================================================================== --- lib/webrick/httpresponse.rb (revision 38944) +++ lib/webrick/httpresponse.rb (revision 38945) @@ -16,11 +16,34 @@ require 'webrick/httpstatus' https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpresponse.rb#L16 module WEBrick ## - # An HTTP response. + # An HTTP response. This is filled in by the service or do_* methods of a + # WEBrick HTTP Servlet. class HTTPResponse - attr_reader :http_version, :status, :header + + ## + # HTTP Response version + + attr_reader :http_version + + ## + # Response status code (200) + + attr_reader :status + + ## + # Response header + + attr_reader :header + + ## + # Response cookies + attr_reader :cookies + + ## + # Response reason phrase ("OK") + attr_accessor :reason_phrase ## @@ -28,13 +51,45 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpresponse.rb#L51 attr_accessor :body - attr_accessor :request_method, :request_uri, :request_http_version + ## + # Request method for this response + + attr_accessor :request_method + + ## + # Request URI for this response + + attr_accessor :request_uri + + ## + # Request HTTP version for this response + + attr_accessor :request_http_version + + ## + # Filename of the static file in this response. Only used by the + # FileHandler servlet. + attr_accessor :filename + + ## + # Is this a keep-alive response? + attr_accessor :keep_alive - attr_reader :config, :sent_size ## - # Creates a new HTTP response object + # Configuration for this response + + attr_reader :config + + ## + # Bytes sent in this response + + attr_reader :sent_size + + ## + # Creates a new HTTP response object. WEBrick::Config::HTTP is the + # default configuration. def initialize(config) @config = config @@ -145,7 +200,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpresponse.rb#L200 ## # Sends the response on +socket+ - def send_response(socket) + def send_response(socket) # :nodoc: begin setup_header() send_header(socket) @@ -162,7 +217,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpresponse.rb#L217 ## # Sets up the headers for sending - def setup_header() + def setup_header() # :nodoc: @reason_phrase ||= HTTPStatus::reason_phrase(@status) @header['server'] ||= @config[:ServerSoftware] @header['date'] ||= Time.now.httpdate @@ -225,7 +280,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/webrick/httpresponse.rb#L280 ## # Sends the headers on +socket+ - def send_header(socket) + def send_header(socket) # :nodoc: if @http_version.major > 0 data = status_line() @header.each{|key, value| @@ -243,7 +298,7 @@ module WEBrick https://github.com/ruby/ruby/blob/trunk/lib/ (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/