lib::HTTP::Daemon

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 55
Index Return to Main Contents

NAME

HTTP::Daemon - a simple http server class

SYNOPSIS

  use HTTP::Daemon;
  use HTTP::Status;

  $d = new HTTP::Daemon;
  print "Please contact me at: <URL:", $d->url, ">\n";
  while ($c = $d->accept) {
      $r = $c->get_request;
      if ($r) {
          if ($r->method eq 'GET' and $r->url->path eq "/xyzzy") {
              # this is *not* recommened practice
              $c->send_file_response("/etc/passwd");
          } else {
              $c->send_error(RC_FORBIDDEN)
          }
      }
      $c = undef;  # close connection
  }

DESCRIPTION

Instances of the HTTP::Daemon class are HTTP/1.1 servers that listens on a socket for incoming requests. The HTTP::Daemon is a sub-class of IO::Socket::INET, so you can do socket operations directly on it.

The accept() method will return when a connection from a client is available. The returned value will be a reference to a object of the HTTP::Daemon::ClientConn class 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 reference.

This HTTP daemon does not fork(2) for you. Your application, i.e. the user of the HTTP::Daemon is reponsible for forking if that is desirable. Also note that the user is responsible for generating responses that conforms to the HTTP/1.1 protocol. The HTTP::Daemon::ClientConn provide some methods that make this easier.

METHODS

The following is a list of methods that are new (or enhanced) relative to the IO::Socket::INET base class.

$d = new HTTP::Daemon

The object constructor takes the same parameters as the IO::Socket::INET constructor. It can also be called without specifying any parameters. The daemon will then set up a listen queue of 5 connections and allocate some random port number. A server that want to bind to some specific address on the standard HTTP port will be constructed like this:

  $d = new HTTP::Daemon
        LocalAddr => 'www.someplace.com',
        LocalPort => 80;

$c = $d->accept([$pkg])

Same as IO::Socket::accept but will return an HTTP::Daemon::ClientConn reference by default. It will return undef if you have specified a timeout and no connection is made within that time.

$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 HTTP::Daemon::ClientConn is also a IO::Socket::INET subclass. Instances of this class are returned by the accept() method of the HTTP::Daemon. The following additional methods are provided:

$c->get_request: Will read data from the client and turn it into a HTTP::Request object which is then returned. Will return undef if reading of the request failed. If it fails, then the HTTP::Daemon::ClientConn object ($c) should be discarded.
The $c->get_request method support HTTP/1.1 content bodies, including chunked transfer encoding with footer and multipart/* types.
$c->antique_client: Returns TRUE if the client speaks the HTTP/0.9 protocol, i.e. no status code or headers should be returned.
$c->send_status_line( [$code, [$mess, [$proto]]] ): Sends the status line back to the client.
$c->send_basic_header( [$code, [$mess, [$proto]]] ): Sends the status line and the ``Date:'' and ``Server:'' headers back to the client.
$c->send_response( [$res] ): Takes a HTTP::Response object as parameter and send it back to the client as the response.
$c->send_redirect( $loc, [$code, [$entity_body]] ): Sends a redirect response back to the client. The location ($loc) can be an absolute or a relative URL. The $code must be one the redirect status codes, and it defaults to ``301 Moved Permanently''
$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 happen to be a directory we will generate a HTML index for it.
$c->send_file($fd);: Copies the file back to the client. The file can be a string (which will be interpreted as a filename) or a reference to a glob.
$c->daemon: Return a reference to the corresponding HTTP::Daemon object.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This document was created by man2html, using the manual pages.
Time: 23:58:15 GMT, February 15, 2023