.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTTP::Daemon::App 3"
.TH HTTP::Daemon::App 3 "2006-11-18" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Daemon::App \- Create 2 or 3 line, fully functional (SSL) HTTP server(s)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use HTTP::Daemon::App;
\&    use MyServers::Foo;
\&    HTTP::Daemon::App::run($MyServers::Foo::daemons, $MyServers::Foo::config);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You can describe one or more \s-1HTTP\s0 daemons in a simple hash and *instantly* 
have a [\-\-start|\-\-stop|\-\-restart] capable daemon that can optionally be \s-1SSL\s0 aware.
.PP
Its also easy to add command line options and has integrated help.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
Each function can be exported but nothing is by default.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "run"
.IX Subsection "run"
Takes 2 arguments, both hashrefs. The first describes tha daemons to run, the second is for config.
.PP
\fIdaemon hashref\fR
.IX Subsection "daemon hashref"
.PP
Hopefully these are self descriptive, this example does two daemons \s-1SSL\s0 and non-SSL:
.PP
.Vb 10
\&    {
\&        \*(Aqthingy\-ssl\*(Aq => {
\&            \*(Aqlabel\*(Aq   => \*(AqHTTPS Thingy\*(Aq,
\&            \*(Aqssl\*(Aq     => 1, # true: HTTP::Daemon::SSL, false: HTTP::Daemon
\&            \*(Aqdaemon\*(Aq  => {
\&                # arguments HTTP::Daemon[::SSL]\->new()
\&                \*(AqLocalPort\*(Aq => 4279,
\&            },
\&            \*(Aqhandler\*(Aq => sub {
\&                my($d, $c, $r, $conf_hr) = @_; # $d, $c, $r from HTTP::Daemon
\&                # handle request
\&            },
\&        },
\&        \*(Aqthingy\*(Aq => {
\&            \*(Aqlabel\*(Aq   => \*(AqHTTP Thingy\*(Aq,
\&            \*(Aqssl\*(Aq     => 0, # true: HTTP::Daemon::SSL, false: HTTP::Daemon
\&            \*(Aqdaemon\*(Aq  => {
\&                # arguments HTTP::Daemon[::SSL]\->new()
\&                \*(AqLocalPort\*(Aq => 4278,
\&            },
\&            \*(Aqhandler\*(Aq => sub {
\&                my($d, $c, $r, $conf_hr) = @_; # $d, $c, $r from HTTP::Daemon
\&                # handle request
\&            },
\&        },
\&    },
.Ve
.PP
\fIconfig hashref\fR
.IX Subsection "config hashref"
.PP
.Vb 10
\&    {
\&        \*(Aqpre_fork\*(Aq => \*(Aq\*(Aq, # set to a code ref it gets called before it forks the child process,  its args are ($handler, $d, $name, $pidfile, $conf)
\&        \*(Aqpst_fork\*(Aq => \*(Aq\*(Aq, # same as pre_fork but run after the fork is done
\&        \*(Aqpid_dir\*(Aq => \*(Aq/var/run/\*(Aq, # default shown
\&        \*(Aqpid_ext\*(Aq => \*(Aq.pid\*(Aq, # default shown
\&        \*(Aqverbose\*(Aq => 0, # example of your custom option that can be used by your handlers and set via \*(Aqopts\*(Aq like below
\&        # \*(Aqlang\*(Aq    => \*(AqLocale::Maketext::Utils handle\*(Aq, not used yet
\&        \*(Aqhelp\*(Aq    => \*(Aq\*(Aq, # default shown, this is added to the useage output.
\&        \*(Aqopts\*(Aq    => {
\&            # default {}, cannot use \-\-stop, \-\-start, or \-\-restart, automagically added to useage line
\&            \*(Aq\-\-version\*(Aq  => sub { print "$0 v1.0\en" },
\&            \*(Aq\-\-verbose\*(Aq => sub { my($daemons_hashref, $conf) = @_;$conf\->{\*(Aqverbose\*(Aq} = 1; },
\&        },
\&        \*(Aqself\*(Aq => "perl $0", # default shown, command used to call \-\-stop & \-\-start on \-\-restart
\&    }
.Ve
.SS "decode_basic_auth"
.IX Subsection "decode_basic_auth"
Given the encoded basic auth passed by the browser 
(or given the \*(L"$r\*(R" object from HTTP::Daemon, the 'Authorization' header's value) 
this will return the username an password.
.PP
.Vb 2
\&    my ($auth_user, $auth_pass) = decode_basic_auth( $encoded_basic_auth_from_browser );
\&    my($user, $encpass, $uid, $gid, $homedir) = (getpwnam($auth_user))[0, 1, 2, 3, 7];
\&    
\&    if($auth_user && $encpass eq crypt($auth_pass, $encpass) && $user eq $auth_user) {
\&        ... # continue on as authenticated user
.Ve
.SS "send_basic_auth_request"
.IX Subsection "send_basic_auth_request"
Takes two arguments: the \*(L"$c\*(R" object from HTTP::Request, the realm's name (has lame default if not specified)
.PP
It does a 401 that incites the client's authentication challenge (E.g. a browser's drop down login box)
.PP
.Vb 5
\&        ... # continue on as authenticated user
\&        }
\&        else {
\&            HTTP::Daemon::App::send_basic_auth_request($c, \*(AqVault of secrets\*(Aq);
\&        }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTTP::Daemon
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey, <http://drmuey.com/cpan_contact.pl>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Daniel Muey
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.