NAME

Net::Server::HTTP - very basic Net::Server based HTTP server class

TEST ONE LINER

perl -e 'use base qw(Net::Server::HTTP); main->run(port => 8080)'
# will start up an echo server

SYNOPSIS

use base qw(Net::Server::HTTP);
__PACKAGE__->run;

sub process_http_request {
    my $self = shift;

    print "Content-type: text/html\n\n";
    print "<form method=post action=/bam><input type=text name=foo><input type=submit></form>\n";

    require Data::Dumper;
    local $Data::Dumper::Sortkeys = 1;

    require CGI;
    my $form = {};
    my $q = CGI->new; $form->{$_} = $q->param($_) for $q->param;

    print "<pre>".Data::Dumper->Dump([\%ENV, $form], ['*ENV', 'form'])."</pre>";
}

DESCRIPTION

Even though Net::Server::HTTP doesn't fall into the normal parallel of the other Net::Server flavors, handling HTTP requests is an often requested feature and is a standard and simple protocol.

Net::Server::HTTP begins with base type MultiType defaulting to Net::Server::Fork. It is easy to change it to any of the other Net::Server flavors by passing server_type => $other_flavor in the server configurtation. The port has also been defaulted to port 80 - but could easily be changed to another through the server configuration. You can also very easily add ssl by including, proto=>"ssl" and provide a SSL_cert_file and SSL_key_file.

For example, here is a basic server that will bind to all interfaces, will speak both HTTP on port 8080 as well as HTTPS on 8443, and will speak both IPv4, as well as IPv6 if it is available.

use base qw(Net::Server::HTTP);

__PACKAGE__->run(
    port  => [8080, "8443/ssl"],
    ipv   => '*', # IPv6 if available
    SSL_key_file  => '/my/key',
    SSL_cert_file => '/my/cert',
);

METHODS

_init_access_log

Used to open and initialize any requested access_log (see access_log_file and access_log_format).

_tie_client_stdout

Used to initialize automatic response header parsing.

process_http_request

Will be passed the client handle, and will have STDOUT and STDIN tied to the client.

During this method, the %ENV will have been set to a standard CGI style environment. You will need to be sure to print the Content-type header. This is one change from the other standard Net::Server base classes.

During this method you can read from %ENV and STDIN just like a normal HTTP request in other web servers. You can print to STDOUT and Net::Server will handle the header negotiation for you.

Note: Net::Server::HTTP has no concept of document root or script aliases or default handling of static content. That is up to the consumer of Net::Server::HTTP to work out.

Net::Server::HTTP comes with a basic %ENV display installed as the default process_http_request method.

process_request

This method has been overridden in Net::Server::HTTP - you should not use it while using Net::Server::HTTP. This overridden method parses the environment and sets up request alarms and handles dying failures. It calls process_http_request once the request is ready and headers have been parsed.

process_headers

Used to read in the incoming headers and set the ENV.

_init_http_request_info

Called at the end of process_headers. Initializes the contents of http_request_info.

http_request_info

Returns a hashref of information specific to the current request. This information will be used for logging later on.

send_status

Takes an HTTP status and a message. Sends out the correct headers.

send_500

Calls send_status with 500 and the argument passed to send_500.

c<log_http_request>

Called at the end of post_process_request. The default method looks for the default access_log_format and checks if logging was initilized during _init_access_log. If both of these exist, the http_request_info is formatted using http_log_format and the result is logged.

http_log_format

Takes a format string, and request_info and returns a formatted string. The format should follow the apache mod_log_config specification. As in the mod_log_config specification, backslashes, quotes should be escaped with backslashes and you may also include \n and \t characters as well.

The following is a listing of the available parameters as well as sample output based on a very basic HTTP server.

%%                %                 # a percent
%a                ::1               # remote ip
%A                ::1               # local ip
%b                83                # response size (- if 0) Common Log Format
%B                83                # response size
%{bar}C           baz               # value of cookie by that name
%D                916               # elapsed in microseconds
%{HTTP_COOKIE}e   bar=baz           # value of %ENV by that name
%f                -                 # filename - unused
%h                ::1               # remote host if lookups are on, remote ip otherwise
%H                http              # request protocol
%{Host}i          localhost:8080    # request header by that name
%I                336               # bytes received including headers
%l                -                 # remote logname - unsused
%m                GET               # request method
%n                Just a note       # http_note by that name
%{Content-type}o  text/html         # output header by that name
%O                189               # response size including headers
%p                8080              # server port
%P                22999             # pid - does not support %{tid}P
q                 ?hello=there      # query_string including ? (- otherwise)
r                 GET /bam?hello=there HTTP/1.1      # the first line of the request
%s                200               # response status
%u                -                 # remote user - unused
%U                /bam              # request path (no query string)
%t                [06/Jun/2012:12:14:21 -0600]       # http_log_time standard format
%t{%F %T %z}t     [2012-06-06 12:14:21 -0600]        # http_log_time with format
%T                0                 # elapsed time in seconds
%v                localhost:8080    # http_log_vhost - partial implementation
%V                localhost:8080    # http_log_vhost - partial implementation
%X                -                 # Connection completed and is 'close' (-)

Additionally, the log parsing allows for the following formats.

%>s               200               # status of last request
%<s               200               # status of original request
%400a             -                 # remote ip if status is 400
%!400a            ::1               # remote ip if status is not 400
%!200a            -                 # remote ip if status is not 200

There are few bits not completely implemented:

> and <    # There is no internal redirection
%I         # The answer to this is based on header size and Content-length
             instead of the more correct actual number of bytes read though
             in common cases those would be the same.
%X         # There is no Connection keepalive in the default server.
%v and %V  # There are no virtual hosts in the default HTTP server.
%{tid}P    # The default servers are not threaded.

See the access_log_format option for how to set a different format as well as to see the default string.

exec_cgi

Allow for calling an external script as a CGI. This will use IPC::Open3 to fork a new process and read/write from it.

use base qw(Net::Server::HTTP);
__PACKAGE__->run;

sub process_http_request {
    my $self = shift;

    if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?= $ | /) }{}x) {
       $ENV{'SCRIPT_NAME'} = $1;
       my $file = "/var/www/cgi-bin/foo"; # assuming this exists
       return $self->exec_cgi($file);
    }

    print "Content-type: text/html\n\n";
    print "<a href=/foo>Foo</a>";
}

At this first release, the parent server is not tracking the child script which may cause issues if the script is running when a HUP is received.

http_log_time

Used to implement the %t format.

http_log_env

Used to implement the %e format.

http_log_cookie

Used to implement the %C format.

http_log_header_in

used to implement the %i format.

http_log_note

Used to implement the %n format.

http_note

Takes a key and an optional value. If passed a key and value, sets the note for that key. Always returns the value. These notes currently only are used for %{key}n output format.

http_log_header_out

Used to implement the %o format.

http_log_pid

Used to implement the %P format.

http_log_vhost

Used to implement the %v and %V formats.

http_log_constat

Used to implement the %X format.

exec_trusted_perl

Allow for calling an external perl script. This method will still fork, but instead of using IPC::Open3, it simply requires the perl script. That means that the running script will be able to make use of any shared memory. It also means that the STDIN/STDOUT/STDERR handles the script is using are those directly bound by the server process.

use base qw(Net::Server::HTTP);
__PACKAGE__->run;

sub process_http_request {
    my $self = shift;

    if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?= $ | /) }{}x) {
       $ENV{'SCRIPT_NAME'} = $1;
       my $file = "/var/www/cgi-bin/foo"; # assuming this exists
       return $self->exec_trusted_perl($file);
    }

    print "Content-type: text/html\n\n";
    print "<a href=/foo>Foo</a>";
}

At this first release, the parent server is not tracking the child script which may cause issues if the script is running when a HUP is received.

OPTIONS

In addition to the command line arguments of the Net::Server base classes you can also set the following options.

max_header_size

Defaults to 100_000. Maximum number of bytes to read while parsing headers.

server_revision

Defaults to Net::Server::HTTP/$Net::Server::VERSION.

timeout_header

Defaults to 15 - number of seconds to wait for parsing headers.

timeout_idle

Defaults to 60 - number of seconds a request can be idle before the request is closed.

access_log_file

Defaults to undef. If true, this represents the location of where the access log should be written to. If a special value of STDERR is passed, the access log entry will be writting to the same location as the ERROR log.

access_log_format

Should be a valid apache log format that will be passed to http_log_format. See the http_log_format method for more information.

The default value is the NCSA extended/combined log format:

'%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'

TODO

Add support for writing out HTTP/1.1.

AUTHOR

Paul T. Seamons paul@seamons.com

THANKS

See Net::Server

SEE ALSO

Please see also Net::Server::Fork, Net::Server::INET, Net::Server::PreFork, Net::Server::PreForkSimple, Net::Server::MultiType, Net::Server::Single Net::Server::SIG Net::Server::Daemonize Net::Server::Proto