=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

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

=head1 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;

=head1 DESCRIPTION

This module extends the basic L<Any::Daemon|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 L<documentation in the base class|Any::Daemon/"DESCRIPTION">.
 
=head2 Limitations

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

=over 4

=item only one socket

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

=item no proxy support

=back

=head1 METHODS

See L<documentation in the base class|Any::Daemon/"METHODS">.
 
=head2 Constructors

See L<documentation in the base class|Any::Daemon/"Constructors">.
 
=over 4

=item Any::Daemon::HTTP-E<gt>B<new>(OPTIONS)

Also see the option descriptions of L<Any::Daemon::new()|Any::Daemon/"Constructors">.

When C<documents> or C<handler> is passed, then a virtual host will
be created from that.  It is nicer to create the vhost explicitly.
If you L<run()|Any::Daemon::HTTP/"Action"> 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
  vhosts                             <default>
  workdir           Any::Daemon      current working directory

=over 2

=item documents => DIRECTORY

See L<Any::Daemon::HTTP::VirtualHost::new(documents)|Any::Daemon::HTTP::VirtualHost/"Constructors">

=item group => GID|GROUPNAME

=item handler => CODE|HASH

Equivalent to C<handlers>.

=item handlers => CODE|HASH

See  L<Any::Daemon::HTTP::VirtualHost::new(handlers)|Any::Daemon::HTTP::VirtualHost/"Constructors">

=item host => HOSTNAME[:PORT]

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

=item pid_file => FILENAME

=item server_id => STRING

=item 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.

=item socket => SOCKET

=item 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.

=item use_ssl => BOOLEAN

=item user => UID|USERNAME

=item vhosts => VHOST|HASH-of-OPTIONS|PACKAGE|ARRAY

For OPTIONS, see L<addVirtualHost()|Any::Daemon::HTTP/"Virtual host administration">.  Provide one or an ARRAY of
virtual host configurations, either by L<Any::Daemon::HTTP::VirtualHost|Any::Daemon::HTTP::VirtualHost>
objects or by the OPTIONS to create such objects.

=item workdir => DIRECTORY

=back

=back

=head2 Accessors

See L<documentation in the base class|Any::Daemon/"Accessors">.
 
=over 4

=item $obj-E<gt>B<host>()

=item $obj-E<gt>B<socket>()

=item $obj-E<gt>B<useSSL>()

=item $obj-E<gt>B<workdir>()

See L<Any::Daemon/"Accessors">

=back

=head2 Virtual host administration

=over 4

=item $obj-E<gt>B<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 L<Any::Daemon::HTTP::VirtualHost::new()|Any::Daemon::HTTP::VirtualHost/"Constructors"> for OPTIONS.

See the manual page for L<Any::Daemon::HTTP::VirtualHost|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
    );

=item $obj-E<gt>B<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.

=item $obj-E<gt>B<virtualHost>(NAME)

Find the virtual host with the NAME or alias.  Returns the
L<Any::Daemon::HTTP::VirtualHost|Any::Daemon::HTTP::VirtualHost> or C<undef>.

=back

=head2 Action

See L<documentation in the base class|Any::Daemon/"Action">.
 
=over 4

=item $obj-E<gt>B<run>(OPTIONS)

When there is no vhost yet, one will be created.  When only one vhost
is active, you may pass C<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

=over 2

=item background => BOOLEAN

=item child_died => CODE

=item child_task => CODE

=item kill_childs => CODE

=item max_childs => INTEGER

=item new_connection => CODE

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

=item reconfigure => CODE

=back

=back

=head1 SEE ALSO

This module is part of Any-Daemon-HTTP distribution version 0.21,
built on October 15, 2013. Website: F<http://perl.overmeer.net/any-daemon/>

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>

