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
  , host      => '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
  ( host      => '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
  ( host      => '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, 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.

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

See "DETAILS" for a list of features and limitations.

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
 handler                            undef
 handlers                           undef
 host                               <from socket>
 on_error                           undef
 pid_file          Any::Daemon      undef
 server_id                          <program name>
 session_class                      Any::Daemon::HTTP::Session
 socket                             <created internally>
 standard_headers                   [ ]
 use_ssl                            <false>
 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
handler => CODE|HASH: Equivalent to handlers.
handlers => CODE|HASH: See Any::Daemon::HTTP::VirtualHost::new(handlers)
host => HOSTNAME[:PORT]
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
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.
socket => SOCKET
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.
use_ssl => BOOLEAN
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.
workdir => DIRECTORY

Accessors

See documentation in the base class.

$obj->host()
$obj->socket()
$obj->useSSL()
$obj->workdir(): See "Accessors" in Any::Daemon

Virtual host administration

$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->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
 max_childs      Any::Daemon      10
 new_connection                   <undef>
 reconfigure     Any::Daemon      ignore

background => BOOLEAN
child_died => CODE
child_task => CODE
kill_childs => CODE
max_childs => INTEGER
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

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)
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

Of course, the wishlist (of missing features) is quite long. To list the most important limitations of the current implementation:

only one socket

You can currently only use one socket, either plain or SSL.
no proxy support

LICENSE

Copyrights 2013 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

Virtual host administration

Action

DETAILS

Server supported features

Server limitations

SEE ALSO

LICENSE

Module Install Instructions