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.
- "exec_fork_hook"
- This method is called after the fork of exec_trusted_perl
and exec_cgi hooks. It is passed the pid (0 if the child) and the file
being ran. Note, that the hook will not be called from the child during
exec_cgi.
- "http_dispatch"
- Called if the default process_http_request and
process_request methods have not been overridden and "app"
configuration parameters have been passed. In this case this replaces the
default echo server. You can also enable this subsystem for your own
direct use by setting enable_dispatch to true during configuration. See
the "app" configuration item. It will be passed a dispatch qr
(regular expression) generated during _check_dispatch, and a dispatch
table. The qr will be applied to path_info. This mechanism could be used
to augment Net::Server::HTTP with document root and virtual host
capabilities.
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 writing 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\"'
- app
- Takes one or more items and registers them for dispatch.
Arguments may be supplied as an arrayref containing a location/target
pairs, a hashref containing a location/target pairs, a bare code ref that
will use "/" as the location and the codref as the target, a
string with a space indicating "location target", a string
containing "location=target", or finally a string that will be
used as both location and target. For items passed as an arrayref or
hashref, the target may be a coderef which will be called and should
handle the request. In all other cases the target should be a valid
executable suitable for passing to exec_cgi.
The locations will be added in the order that they are configured. They will
be added to a regular expression which will be applied to the incoming
PATH_INFO string. If the match is successful, the $ENV{'SCRIPT_NAME'} will
be set to the matched portion and the matched portion will be removed from
$ENV{'PATH_INFO'}.
Once an app has been passed, it is necessary for the server to listen on /.
Therefore if "/" has not been specifically configured for
dispatch, the first found dispatch target will also be used to handle
"/".
For convenience, if the log_level is 2 or greater, the dispatch table is
output to the log.
This mechanism is left as a generic mechanism suitable for overriding by
servers meant to handle more complex dispatch. At the moment there is no
handling of virtual hosts. At some point we will add in the default
ability to play static content and likely for the ability to configure
virtual hosts - or that may have to wait for a third party module.
app => "/home/paul/foo.cgi",
# Dispatch: /home/paul/foo.cgi => home/paul/foo.cgi
# Dispatch: / => home/paul/foo.cgi (default)
app => "../../foo.cgi",
app => "./bar.cgi",
app => "baz ./bar.cgi",
app => "bim=./bar.cgi",
# Dispatch: /foo.cgi => ../../foo.cgi
# Dispatch: /bar.cgi => ./bar.cgi
# Dispatch: /baz => ./bar.cgi
# Dispatch: /bim => ./bar.cgi
# Dispatch: / => ../../foo.cgi (default)
app => "../../foo.cgi",
app => "/=./bar.cgi",
# Dispatch: /foo.cgi => ../../foo.cgi
# Dispatch: / => ./bar.cgi
# you could also do this on the commandline
net-server HTTP app ../../foo.cgi app /=./bar.cgi
# extended options when configured from code
Net::Server::HTTP->run(app => { # loses order of matching
'/' => sub { ... },
'/foo' => sub { ... },
'/bar' => '/path/to/some.cgi',
});
Net::Server::HTTP->run(app => [
'/' => sub { ... },
'/foo' => sub { ... },
'/bar' => '/path/to/some.cgi',
]);
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