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

SEE ALSO

This module is part of Any-Daemon-HTTP distribution version 0.23, built on November 28, 2013. Website: http://perl.overmeer.net/any-daemon/

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

cpanm Any::Daemon::HTTP

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