The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Any-Daemon-HTTP-0.29
River stage zero No dependents
++
/ Any::Daemon::HTTP

NAME

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

INHERITANCE

 Any::Daemon::HTTP
   is an Any::Daemon

SYNOPSIS

  #
  # Simpelest
  #

  use Log::Report;
  use Any::Daemon::HTTP;
  my $http = Any::Daemon::HTTP->new
    ( handler   => \&handler
    , listen    => 'server.example.com:80'
    , new_child => sub { dispatcher SYSLOG, 'default' }
    , %daemon_opts
    );

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

  #
  # Clean style
  #

  use Log::Report;
  use Any::Daemon::HTTP;
  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.

Extends "DESCRIPTION" in Any::Daemon.

METHODS

Extends "METHODS" in Any::Daemon.

Constructors

Extends "Constructors" in Any::Daemon.

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
  protocol                           HTTP and HTTPS by port-number
  proxies                            <default>
  proxy_class                        Any::Daemon::HTTP::Proxy
  server_id                          <program name>
  session_class                      Any::Daemon::HTTP::Session
  show_in_ps                         true
  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
protocol => 'HTTP'|'HTTPS'|'FCGI'

[0.29] Specify which kind of connection has to be managed: plain HTTP, HTTP over SSL, or HTTP over FCGI.

proxies => PROXY|PACKAGE|\%options|ARRAY

[0.24] For %options, see addProxy(). The %options are passed to addProxy(), to create a proxy object under fly. You may also pass an Any::Daemon::HTTP::Proxy objects or by the %options to create such objects. An ARRAY contains a mixture of proxy definitions. Same as option 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.

show_in_ps => BOOLEAN

Show the status of the childs in "ps". On some systems, this looks nice, but on others there are various mutilations.

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|PACKAGE|\%options|ARRAY

The %options are passed to addVirtualHost(), to create a virtual host object under fly. You may also pass an initialized Any::Daemon::HTTP::VirtualHost object, or a PACKAGE name to be used for the default vhost. An ARRAY contains a mixture of vhost definitions. [0.24] Same as option vhost.

workdir => DIRECTORY

Accessors

Extends "Accessors" in Any::Daemon.

$obj->hosts()

Returns a list of hostnames used to connect to the sockets.

$obj->pidFilename()

Inherited, see "Accessors" in Any::Daemon

$obj->protocol()

Returns HTTP, HTTPS, or FCGI to express the procotol used. All implementations are based on HTTP::Daemon (part of LWP)

$obj->sockets()

Returns all the sockets we listen on. This list is the result of new(listen).

$obj->workdir()

Inherited, 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|\%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|\%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 %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

Extends "Action" in Any::Daemon.

$obj->newChild($select)

[0.28] Called by default when a new task process has been generated. It gets the IO::Select object as only parameter (for now), which is the only thing created before this call. After this call, the process starts waiting for connections.

This parameter/method is typically used to (re)connect to the database, or setup logging.

$obj->newConnection($session)

[0.28] Called by default when a new client has been accepted. See run(new_connection).

$obj->psTitle($string)
$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      'childDied'
  child_task          Any::Daemon      <accept http connections>
  kill_childs         Any::Daemon      'killChilds'
  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_child                            'newChild'
  new_connection                       'newConnection'
  reconfigure         Any::Daemon      'reconfigDaemon'
  req_time_bonus                       5
  run_task            Any::Daemon      undef
background => BOOLEAN
child_died => CODE|METHOD
child_task => CODE|METHOD
kill_childs => CODE|METHOD
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_child => CODE|METHOD

[0.28] run code when a new child process is started. This will run before the task starts waiting for connections. See newChild()

new_connection => CODE|METHOD

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

[0.28] Also a METHOD name. See newConnection()

reconfigure => CODE|METHOD
req_time_bonus => SECONDS
run_task => CODE|METHOD

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

SEE ALSO

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

LICENSE

Copyrights 2013-2019 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://dev.perl.org/licenses/