mirror of
https://git.proxmox.com/git/libhttp-daemon-perl
synced 2025-10-04 19:14:10 +00:00
238 lines
10 KiB
Plaintext
238 lines
10 KiB
Plaintext
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:", $d->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.
|
|
|