NAME

Any::Daemon::HTTP - preforking Apache/Plack-like webserver

INHERITANCE

Any::Daemon::HTTP
  is a Any::Daemon

SYNOPSIS

#
# Simpelest
#

my $http = Any::Daemon::HTTP->new
  ( handler   => \&handler
  , listen    => 'server.example.com:80'
  , %daemon_opts
  );

sub handler($$$$$)
{   my ($server, $client, $request, $vhost, $dir) = @_;
    return HTTP::Response->new(500);
}

#
# Clean style
#

my $http = Any::Daemon::HTTP->new
  ( listen    => 'server.example.com:80'
  );

$http->addVirtualHost
  ( name      => 'www.example.com'
  , aliases   => 'example.com'
  , documents => '/www/srv/example.com/http'
  , handler   => \&handler
  );

$http->run;

#
# Limited server
#

my $http = Any::Daemon::HTTP->new
  ( listen    => 'www.example.com'
  , documents => '/www/srv/example.com/http'
  , handler   => \&handler
  , %daemon_opts
  );
$http->run;

DESCRIPTION

This module extends the basic Any::Daemon with childs which handle http connections. This daemon does understand virtual hosts, per directory configuration, access rules, uri rewrites, proxies, and other features of Apache and Plack. But you can also use it for a very simple HTTP server.

The HTTP/1.1 protocol implementation of HTTP::Daemon is (ab)used. See "DETAILS" for a list of features and limitations.

Please support my development work by submitting bug-reports, patches and (if available) a donation.

See documentation in the base class.

METHODS

See documentation in the base class.

Constructors

See documentation in the base class.

Any::Daemon::HTTP->new(OPTIONS)

Also see the option descriptions of Any::Daemon::new().

When documents or handler is passed, then a virtual host will be created from that. It is nicer to create the vhost explicitly. If you run() without host or documents or any vhost definition, then the defaults are used to create a default vhost.

-Option          --Defined in     --Default
 documents                          undef
 group             Any::Daemon      undef
 handlers                           undef
 listen                             <required>
 on_error                           undef
 pid_file          Any::Daemon      undef
 proxies                            <default>
 proxy_class                        Any::Daemon::HTTP::Proxy
 server_id                          <program name>
 session_class                      Any::Daemon::HTTP::Session
 standard_headers                   [ ]
 user              Any::Daemon      undef
 vhost_class                        Any::Daemon::HTTP::VirtualHost
 vhosts                             <default>
 workdir           Any::Daemon      current working directory

documents => DIRECTORY: See Any::Daemon::HTTP::VirtualHost::new(documents).
group => GID|GROUPNAME
handlers => CODE|HASH: See Any::Daemon::HTTP::VirtualHost::new(handlers). You can also use the option name handler.
listen => SOCKET|HOSTNAME[:PORT]|IPADDR[:PORT]|ARRAY: Specifies one or more SOCKETs, HOSTNAMEs, or IP-ADDResses where connections can come in. Old option names host and socket are also still available.
on_error => CODE: [0.21] This handler is called when an 4xx or 5xx error response has been produced. The result of this function should be the new response (may be the same as the incoming)
pid_file => FILENAME
proxies => VHOST|HASH-of-OPTIONS|PACKAGE|ARRAY: [0.24] For OPTIONS, see addProxy(). Provide one or an ARRAY of proxy configurations, either by Any::Daemon::HTTP::Proxy objects or by the OPTIONS to create such objects. You can also use the option name proxy.
proxy_class => PACKAGE: [0.24] The PACKAGE must extend the default class.
server_id => STRING
session_class => PACKAGE: [0.21] The PACKAGE must extend the default class. The extended class may be used to implement loading and saving session information, or adding abstraction.
standard_headers => ARRAY: Pass a list of key-value pairs which will be added to each produced response. They are fed into HTTP::Headers subroutine push_header.
user => UID|USERNAME
vhost_class => PACKAGE: [0.22] The PACKAGE must extend the default class. See the "DETAILS" in Any::Daemon::HTTP::VirtualHost about creating your own virtual hosts.
vhosts => VHOST|HASH-of-OPTIONS|PACKAGE|ARRAY: For OPTIONS, see addVirtualHost(). Provide one or an ARRAY of virtual host configurations, either by Any::Daemon::HTTP::VirtualHost objects or by the OPTIONS to create such objects. [0.24] You can also use the option name vhost.
workdir => DIRECTORY

Accessors

See documentation in the base class.

$obj->sockets(): Returns all the sockets we listen on. This list is the result of new(listen).
$obj->workdir(): See "Accessors" in Any::Daemon

Host administration

VirtualHosts and a global proxy can be added in a any order. They can also be added at run-time!

When a request arrives, it contains a Host header which is used to select the right object. When a VirtualHost has this name or alias, that will be address. Otherwise, if there are global proxy objects, they are tried one after the other to see whether the forwardRewrite() reports that it accepts the request. If this all fails, then the request is redirected to the host named (or aliased) 'default'. As last resort, you get an error.

$obj->addProxy(OBJECT|HASH-of-OPTIONS|OPTIONS)

Add a Any::Daemon::HTTP::Proxy object which has a proxy_map, about how to handle requests for incoming hosts. The proxy settings will be tried in order of addition, only when there are no virtual hosts addressed.

$obj->addVirtualHost(VHOST|HASH-of-OPTIONS|OPTIONS)

Adds a new virtual host to the knowledge of the daemon. Can be used at run-time, until the daemon goes into 'run' mode (starts forking childs) The added virtual host object is returned.

The VHOST is an already prepared VirtualHost object. With a (HASH-of) OPTIONS, the VirtualHost object gets created for you with those OPTIONS. See Any::Daemon::HTTP::VirtualHost::new() for OPTIONS.

See the manual page for Any::Daemon::HTTP::VirtualHost on how you can cleanly extend the class for your own purpose.

example:

# Simple version
$http->addVirtualHost
  ( name      => 'images'
  , aliases   => 'images.example.com'
  , documents => '/home/www/images
  );

# Own virtual host, usually in separate pm-file
{ package My::VHost;
  use parent 'Any::Daemon::HTTP::VirtualHost';
  ...
}
my $vhost = My::VHost->new(...);
$http->addVirtualHost($vhost);

# Implicitly add virtual hosts
push @vhosts, $vhost;
my $http = Any::Daemon::HTTP->new
  ( ...
  , vhosts    => \@vhosts
  );

$obj->findProxy(SESSION, REQUEST, HOST)

[0.24] Find the first proxy which is mapping the URI of the REQUEST. Returns a pair, containing the proxy and the location where it points to.

Usually, in a proxy, the request needs to be in absolute form in the request header. However, we can be more

$obj->proxies()

[0.24] Returns a list with all added proxy objects.

$obj->removeVirtualHost(VHOST|NAME|ALIAS)

Remove all name and alias registrations for the indicated virtual host. Silently ignores non-existing vhosts. The removed virtual host object is returned.

$obj->virtualHost(NAME)

Find the virtual host with the NAME or alias. Returns the Any::Daemon::HTTP::VirtualHost or undef.

Action

See documentation in the base class.

$obj->run(OPTIONS)

When there is no vhost yet, one will be created. When only one vhost is active, you may pass handle_request (see the vhost docs).

-Option            --Defined in     --Default
 background          Any::Daemon      <true>
 child_died          Any::Daemon      spawn new childs
 child_task          Any::Daemon      <accept http connections>
 kill_childs         Any::Daemon      send sigterm
 linger                               undef
 max_childs          Any::Daemon      10
 max_conn_per_child                   10_000
 max_req_per_child                    100_000
 max_req_per_conn                     100
 max_time_per_conn                    120
 new_connection                       <undef>
 reconfigure         Any::Daemon      ignore
 req_time_bonus                       5

background => BOOLEAN

child_died => CODE

child_task => CODE

kill_childs => CODE

linger => SECONDS

When defined, it sets the maximim time a client may stay connected to collect the data after the connection is closed by the server. When zero, the last response may get lost, because the connection gets reset immediately. Without linger, browsers may block the server resource for a long time. So, a linger of a few seconds (when you only have small files) will help protecting your server.

This setting determines the minimum time for a save server reboot. When the daemon is stopped, the client may still keeps its socket. The restart of the server may fail with "socket already in use".

max_childs => INTEGER

max_conn_per_child => INTEGER

[0.24] Average maximum number of connections which are handled per process, before it commits suicide to cleanup garbaged memory. The parent will start a new process.

This value gets a random value in 10% range added to subtracted to avoid that all childs reset at the same time. So, for the default value, 9_000 upto 11_000 connections will be served before a reset.

max_req_per_child => INTEGER

[0.24] maximum number of HTTP requests accepted by all connections for one process.

max_req_per_conn => INTEGER

[0.24] maximum number of HTTP requests handled in one connection.

max_time_per_conn => SECONDS

Maximum time a connection will stay alive. When the time expires, the process will forcefully killed. For each request, req_time_bonus seconds are added. This may be a bit short when your files are large.

new_connection => CODE

The CODE is called on each new connection made. It gets as parameters the server (this object) and the connection (an Any::Daemon::HTTP::Session extension)

reconfigure => CODE

req_time_bonus => SECONDS

DETAILS

Server supported features

Many often used features are supported

HTTP/1.1 protocol

Supported by via the HTTP::Daemon connection implementation, which is gracefully hijacked. Messages are HTTP::Request and HTTP::Response objects, borrowed from LWP.
virtual hosts

Multiple "hosts" listening on the same port, abstracted in Any::Daemon::HTTP::VirtualHost objects. The vhosts have a name and may have a number of aliases.
directories per VirtualHost

One or more "directory" configurations may be added, which may be nested. They are represened by a Any::Daemon::HTTP::Directory objects. Each "directory" maps a "path" in the request to a directory on disk.
allow/deny per Directory

Supports CIDR and hostname based access restrictions.
directory lists per Directory

When permitted and no index.html file is found, a listing is generated.
user directories per VirtualHost

One directory object can be a Any::Daemon::HTTP::UserDirs, managing user directories (request paths which start with /~$username)
proxies
static content caching

Reduce retransmitting files, supporting ETag and Last-Modified.
rewrite rules per VirtualHost

Translate incoming request paths into new paths in the same vhost.
redirection rules per VirtualHost

Translate incoming request paths into browser redirects.
dynamic content handlers per VirtualHost

When there is no matching file, a handler will be called to produce the required information. The default handler will produce 404 errors.
dynamic content caching

Reduce transmitting dynamic content using ETag and MD5's

Server limitations

Ehhh...

LICENSE

Copyrights 2013-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

To install Any::Daemon::HTTP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Any::Daemon::HTTP

CPAN shell

perl -MCPAN -e shell
install Any::Daemon::HTTP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Constructors

Accessors

Host administration

Action

DETAILS

Server supported features

Server limitations

SEE ALSO

LICENSE

Module Install Instructions