From 64ffbaec18717f99cb80441d8b474868e39939fb Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Sat, 18 Feb 2012 12:24:17 +0000 Subject: HTTP-Daemon-6.01 --- README | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..be5a20a --- /dev/null +++ b/README @@ -0,0 +1,237 @@ +NAME + HTTP::Daemon - a simple http server class + +SYNOPSIS + use HTTP::Daemon; + use HTTP::Status; + + my $d = HTTP::Daemon->new || die; + print "Please contact me at: url, ">\n"; + while (my $c = $d->accept) { + while (my $r = $c->get_request) { + if ($r->method eq 'GET' and $r->uri->path eq "/xyzzy") { + # remember, this is *not* recommended practice :-) + $c->send_file_response("/etc/passwd"); + } + else { + $c->send_error(RC_FORBIDDEN) + } + } + $c->close; + undef($c); + } + +DESCRIPTION + Instances of the `HTTP::Daemon' class are HTTP/1.1 servers that listen + on a socket for incoming requests. The `HTTP::Daemon' is a subclass of + `IO::Socket::INET', so you can perform socket operations directly on it + too. + + The accept() method will return when a connection from a client is + available. The returned value will be an `HTTP::Daemon::ClientConn' + object which is another `IO::Socket::INET' subclass. Calling the + get_request() method on this object will read data from the client and + return an `HTTP::Request' object. The ClientConn object also provide + methods to send back various responses. + + This HTTP daemon does not fork(2) for you. Your application, i.e. the + user of the `HTTP::Daemon' is responsible for forking if that is + desirable. Also note that the user is responsible for generating + responses that conform to the HTTP/1.1 protocol. + + The following methods of `HTTP::Daemon' are new (or enhanced) relative + to the `IO::Socket::INET' base class: + + $d = HTTP::Daemon->new + $d = HTTP::Daemon->new( %opts ) + The constructor method takes the same arguments as the + `IO::Socket::INET' constructor, but unlike its base class it can + also be called without any arguments. The daemon will then set up a + listen queue of 5 connections and allocate some random port number. + + A server that wants to bind to some specific address on the standard + HTTP port will be constructed like this: + + $d = HTTP::Daemon->new( + LocalAddr => 'www.thisplace.com', + LocalPort => 80, + ); + + See IO::Socket::INET for a description of other arguments that can + be used configure the daemon during construction. + + $c = $d->accept + $c = $d->accept( $pkg ) + ($c, $peer_addr) = $d->accept + This method works the same the one provided by the base class, but + it returns an `HTTP::Daemon::ClientConn' reference by default. If a + package name is provided as argument, then the returned object will + be blessed into the given class. It is probably a good idea to make + that class a subclass of `HTTP::Daemon::ClientConn'. + + The accept method will return `undef' if timeouts have been enabled + and no connection is made within the given time. The timeout() + method is described in IO::Socket. + + In list context both the client object and the peer address will be + returned; see the description of the accept method IO::Socket for + details. + + $d->url + Returns a URL string that can be used to access the server root. + + $d->product_tokens + Returns the name that this server will use to identify itself. This + is the string that is sent with the `Server' response header. The + main reason to have this method is that subclasses can override it + if they want to use another product name. + + The default is the string "libwww-perl-daemon/#.##" where "#.##" is + replaced with the version number of this module. + + The `HTTP::Daemon::ClientConn' is a `IO::Socket::INET' subclass. + Instances of this class are returned by the accept() method of + `HTTP::Daemon'. The following methods are provided: + + $c->get_request + $c->get_request( $headers_only ) + This method reads data from the client and turns it into an + `HTTP::Request' object which is returned. It returns `undef' if + reading fails. If it fails, then the `HTTP::Daemon::ClientConn' + object ($c) should be discarded, and you should not try call this + method again on it. The $c->reason method might give you some + information about why $c->get_request failed. + + The get_request() method will normally not return until the whole + request has been received from the client. This might not be what + you want if the request is an upload of a large file (and with + chunked transfer encoding HTTP can even support infinite request + messages - uploading live audio for instance). If you pass a TRUE + value as the $headers_only argument, then get_request() will return + immediately after parsing the request headers and you are + responsible for reading the rest of the request content. If you are + going to call $c->get_request again on the same connection you + better read the correct number of bytes. + + $c->read_buffer + $c->read_buffer( $new_value ) + Bytes read by $c->get_request, but not used are placed in the *read + buffer*. The next time $c->get_request is called it will consume the + bytes in this buffer before reading more data from the network + connection itself. The read buffer is invalid after $c->get_request + has failed. + + If you handle the reading of the request content yourself you need + to empty this buffer before you read more and you need to place + unconsumed bytes here. You also need this buffer if you implement + services like *101 Switching Protocols*. + + This method always returns the old buffer content and can optionally + replace the buffer content if you pass it an argument. + + $c->reason + When $c->get_request returns `undef' you can obtain a short string + describing why it happened by calling $c->reason. + + $c->proto_ge( $proto ) + Return TRUE if the client announced a protocol with version number + greater or equal to the given argument. The $proto argument can be a + string like "HTTP/1.1" or just "1.1". + + $c->antique_client + Return TRUE if the client speaks the HTTP/0.9 protocol. No status + code and no headers should be returned to such a client. This should + be the same as !$c->proto_ge("HTTP/1.0"). + + $c->head_request + Return TRUE if the last request was a `HEAD' request. No content + body must be generated for these requests. + + $c->force_last_request + Make sure that $c->get_request will not try to read more requests + off this connection. If you generate a response that is not self + delimiting, then you should signal this fact by calling this method. + + This attribute is turned on automatically if the client announces + protocol HTTP/1.0 or worse and does not include a "Connection: + Keep-Alive" header. It is also turned on automatically when HTTP/1.1 + or better clients send the "Connection: close" request header. + + $c->send_status_line + $c->send_status_line( $code ) + $c->send_status_line( $code, $mess ) + $c->send_status_line( $code, $mess, $proto ) + Send the status line back to the client. If $code is omitted 200 is + assumed. If $mess is omitted, then a message corresponding to $code + is inserted. If $proto is missing the content of the + $HTTP::Daemon::PROTO variable is used. + + $c->send_crlf + Send the CRLF sequence to the client. + + $c->send_basic_header + $c->send_basic_header( $code ) + $c->send_basic_header( $code, $mess ) + $c->send_basic_header( $code, $mess, $proto ) + Send the status line and the "Date:" and "Server:" headers back to + the client. This header is assumed to be continued and does not end + with an empty CRLF line. + + See the description of send_status_line() for the description of the + accepted arguments. + + $c->send_header( $field, $value ) + $c->send_header( $field1, $value1, $field2, $value2, ... ) + Send one or more header lines. + + $c->send_response( $res ) + Write a `HTTP::Response' object to the client as a response. We try + hard to make sure that the response is self delimiting so that the + connection can stay persistent for further request/response + exchanges. + + The content attribute of the `HTTP::Response' object can be a normal + string or a subroutine reference. If it is a subroutine, then + whatever this callback routine returns is written back to the client + as the response content. The routine will be called until it return + an undefined or empty value. If the client is HTTP/1.1 aware then we + will use chunked transfer encoding for the response. + + $c->send_redirect( $loc ) + $c->send_redirect( $loc, $code ) + $c->send_redirect( $loc, $code, $entity_body ) + Send a redirect response back to the client. The location ($loc) can + be an absolute or relative URL. The $code must be one the redirect + status codes, and defaults to "301 Moved Permanently" + + $c->send_error + $c->send_error( $code ) + $c->send_error( $code, $error_message ) + Send an error response back to the client. If the $code is missing a + "Bad Request" error is reported. The $error_message is a string that + is incorporated in the body of the HTML entity body. + + $c->send_file_response( $filename ) + Send back a response with the specified $filename as content. If the + file is a directory we try to generate an HTML index of it. + + $c->send_file( $filename ) + $c->send_file( $fd ) + Copy the file to the client. The file can be a string (which will be + interpreted as a filename) or a reference to an `IO::Handle' or + glob. + + $c->daemon + Return a reference to the corresponding `HTTP::Daemon' object. + +SEE ALSO + RFC 2616 + + IO::Socket::INET, IO::Socket + +COPYRIGHT + Copyright 1996-2003, Gisle Aas + + This library is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + -- cgit v1.2.1