Net::Server::HTTP(3)

📦

version 2.014 · 14 versions

💖 Net::Server::HTTP — bestie edition 💖

okay so welcome to the Net::Server::HTTP(3) manual page, bestie 💅 this is part 1 of 3, and we're talking about the very basic Net::Server based HTTP server class. no cap, it's giving “small but useful” energy ✨

🎀 NAME 🎀

Net::Server::HTTP — very basic Net::Server based HTTP server class 💖

🧪 TEST ONE LINER 🧪

bestie, there’s literally a one-liner test. it will start up an echo server 😭🔥

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

🦋 SYNOPSIS 🦋

here’s the shape of it, with the process_http_request sub doing its little form-and-dump moment 🫶:

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 🌸

okay so real talk: 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 HTTP is a standard and simple protocol, so here we are 💖

Net::Server::HTTP begins with base type MultiType defaulting to Net::Server::PreFork 👑 it is easy to change it to any of the other Net::Server flavors by passing server_type => $other_flavor in the server configuration. the port has also been defaulted to port 80 — but it could easily be changed to another through the server configuration 🌈 you can also very easily add ssl by including proto=>"ssl" and providing 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 ✨

okay bestie, buckle up — this is the whole method list, and yeah it's long, but every single one of these matters so we're doing all of them 💅

`_init_access_log`

Used to open and initialize any requested access_log (peep access_log_file and access_log_format for the settings that drive this) 🎀

`_tie_client_stdout`

Used to initialize the automatic response header parsing ✨

`process_http_request`

You get passed the client handle, and STDOUT plus STDIN are tied to that client. 🫶

During this method, %ENV has already been set to a standard CGI-style environment. And here's the thing — you have to be sure to print the Content-type header. That's the one change from the other standard Net::Server base classes, so don't forget it or you'll be sad 😭

During this method you can read from %ENV and STDIN just like a normal HTTP request on any other web server. You can print to STDOUT and Net::Server will handle the header negotiation for you, king behavior 👑

Note: Net::Server::HTTP has no concept of document root, script aliases, or default handling of static content. That is up to the consumer of Net::Server::HTTP to work out. it's giving DIY, fr fr.

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, periodt. This overridden method parses the environment, sets up request alarms, and handles dying failures. It calls process_http_request once the request is ready and the headers have been parsed 💖

`request_denied_hook`

This method has been overridden to call send_400. This is new behavior. To get the previous behavior (where the client was closed without any indication), simply provide

(and yeah — the manpage literally just stops there mid-sentence, bestie, that's all it says 🙈)

`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, an optional message, optional body, and optional generate_body flag. Sends out the correct headers 💅

$self->send_status(500);
$self->send_status(500, 'Internal Server Error');
$self->send_status(500, 'Internal Server Error', "<h1>Internal Server Error</h1><p>Msg</p>");
$self->send_status(500, undef, undef, ['Msg']);

`send_400`

Calls send_status with 400 and the passed arguments as generate_body 🎀

`send_500`

Calls send_status with 500 and the argument passed to send_500 💀

`log_http_request`

(the manpage literally writes this one as c<log_http_request> with a stray c< in front — iconic typo, we keep the info though) Called at the end of post_process_request. The default method looks for the default access_log_format and checks if logging was initialized 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 and 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, plus 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 a few bits that are not completely implemented, and we're being upfront about it 😌

> 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, and also to see the default string 💖

`exec_cgi`

Allows 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 a value, it sets the note for that key. It always returns the value. These notes currently are only used for the %{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`

Allows 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 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 👀 (yes, same warning, it's a whole thing)

`exec_fork_hook`

This method is called after the fork of the 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 🎀

okay so bestie, on top of all the command-line args you already get from the Net::Server base classes, you can also set these 👇

max_header_size — defaults to 100_000. that’s the maximum number of bytes it’ll read while parsing headers. header greed: capped 💅
server_revision — defaults to Net::Server::HTTP/$Net::Server::VERSION. yes literally that string, slay.
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 is the location where the access log should be written to. if the special value STDERR or /dev/stderr is passed, the access log entry gets written to the same location as the ERROR log. if the special value STDOUT or /dev/stdout is passed, the access log entry gets written to standard out ✨
access_log_function — can take a coderef or method name to call when a log_http_request method is called. the formatted log access log message gets passed in.

heads up bestie: functions depending upon stdout will not function during Net::Server::HTTP process_request, because stdout is always tied for the client (and not restored after running). 😭

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 location/target pairs,
- a hashref containing location/target pairs,
- a bare code ref that will use / as the location and the coderef 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 get added in the order that they are configured. they get added to a regular expression which will be applied to the incoming PATH_INFO string. if the match is successful, $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',
]);

default_content_type — default is text/html. it gets set on any responses that have not yet passed a content-type 💖
allow_body_on_all_statuses — by default, content-type and printing a body are not allowed on 204, 304, or 1xx statuses. set this flag to automatically send a content-type on those statuses as well ✨

🌈 TODO 🌈

add support for writing out HTTP/1.1. that’s the whole vibe 💀

💖 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

that’s the page, bestie! 🫶 source/version: perl v5.42.0 · date: 2023-03-15 · page: Net::Server::HTTP(3). now go handle some requests and slay 💅✨

📦 where this page comes from

opensuse-leap 16.0: perl-Net-Server 2.014-bp160.1.12 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms