.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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" ''
'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 (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POE::Component::Server::HTTP 3pm"
.TH POE::Component::Server::HTTP 3pm "2006-05-23" "perl v5.10.0" "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"
POE::Component::Server::HTTP \- Foundation of a POE HTTP Daemon
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\& use POE::Component::Server::HTTP;
\& use HTTP::Status;
\& my $aliases = POE::Component::Server::HTTP\->new(
\&     Port => 8000,
\&     ContentHandler => {
\&           \*(Aq/\*(Aq => \e&handler1,
\&           \*(Aq/dir/\*(Aq => sub { ... },
\&           \*(Aq/file\*(Aq => sub { ... }
\&     },
\&     Headers => { Server => \*(AqMy Server\*(Aq },
\&  );
\&
\&  sub handler {
\&      my ($request, $response) = @_;
\&      $response\->code(RC_OK);
\&      $response\->content("Hi, you fetched ". $request\->uri);
\&      return RC_OK;
\&  }
\&
\&  POE::Kernel\->call($aliases\->{httpd}, "shutdown");
\&  # next line isn\*(Aqt really needed
\&  POE::Kernel\->call($aliases\->{tcp}, "shutdown");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Component::Server::HTTP (PoCo::HTTPD) is a framework for building
custom \s-1HTTP\s0 servers based on \s-1POE\s0. It is loosely modeled on the ideas of
apache and the mod_perl/Apache module.
.PP
It is built alot on work done by Gisle Aas on HTTP::* modules and the \s-1URI\s0
module which are subclassed.
.PP
PoCo::HTTPD lets you register different handler, stacked by directory that
will be run during the cause of the request.
.Sh "Handlers"
.IX Subsection "Handlers"
Handlers are put on a stack in fifo order. The path /foo/bar/baz/honk.txt
will first push the handlers of / then of /foo/ then of /foo/bar/, then of
/foo/bar/baz/, and lastly /foo/bar/baz/honk.txt.  Pay attention to
directories!  A request for /honk will not match /honk/ as you are used to
with apache.  If you want /honk to act like a directory, you should have
a handler for /honk which redirects to /honk/.
.PP
However, there can be only one ContentHandler and if any handler installs
a ContentHandler that will override the old ContentHandler.
.PP
If no handler installs a ContentHandler it will find the closest one
directory wise and use it.
.PP
There is also a special StreamHandler which is a coderef that gets
invoked if you have turned on streaming by doing
\&\f(CW$response\fR\->\fIstreaming\fR\|(1);
.PP
Handlers take the \f(CW$request\fR and \f(CW$response\fR objects as arguments.
.IP "\s-1RC_OK\s0" 4
.IX Item "RC_OK"
Everything is ok, please continue processing.
.IP "\s-1RC_DENY\s0" 4
.IX Item "RC_DENY"
If it is a TransHandler, stop translation handling and carry on with
a PreHandler, if it is a PostHandler do nothing, else return denied to
the client.
.IP "\s-1RC_WAIT\s0" 4
.IX Item "RC_WAIT"
This is a special handler that suspends the execution of the handlers.
They will be suspended until \f(CW$response\fR\->\fIcontinue()\fR is called, this is
usefull if you want to do a long request and not blocck.
.PP
The following handlers are available.
.IP "TransHandler" 4
.IX Item "TransHandler"
TransHandlers are run before the \s-1URI\s0 has been resolved, giving them a chance
to change the \s-1URI\s0. They can therefore not be registred per directory.
.Sp
.Vb 1
\&    new(TransHandler => [ sub {return RC_OK} ]);
.Ve
.Sp
A TransHandler can stop the dispatching of TransHandlers and jump to the next
handler type by specifing \s-1RC_DENY\s0;
.IP "PreHandler" 4
.IX Item "PreHandler"
PreHandlers are stacked by directory and run after TransHandler but
before the ContentHandler. They can change ContentHandler (but beware,
other PreHandlers might also change it) and push on PostHandlers.
.Sp
.Vb 1
\&    new(PreHandler => { \*(Aq/\*(Aq => [sub {}], \*(Aq/foo/\*(Aq => [\e&foo]});
.Ve
.IP "ContentHandler" 4
.IX Item "ContentHandler"
The handler that is supposed to give the content. When this handler
returns it will send the response object to the client. It will
automaticly add Content-Length and Date if these are not set. If the
response is streaming it will make sure the correct headers are
set. It will also expand any cookies which have been pushed onto the
response object.
.Sp
.Vb 1
\&    new(ContentHandler => { \*(Aq/\*(Aq => sub {}, \*(Aq/foo/\*(Aq => \e&foo});
.Ve
.IP "ErrorHandler" 4
.IX Item "ErrorHandler"
This handler is called when there is a read or write error on the socket.
This is most likely caused by the remote side closing the connection.
\&\f(CW$resquest\fR\->is_error and \f(CW$response\fR\->is_error will return true.  Note that
\&\f(CW\*(C`PostHanlder\*(C'\fR will still called, but \f(CW\*(C`TransHandler\*(C'\fR and \f(CW\*(C`PreHandler\*(C'\fR
won't be.  It is a map to coderefs just like ContentHandler is.
.IP "PostHandler" 4
.IX Item "PostHandler"
These handlers are run after the socket has been flushed.
.Sp
.Vb 1
\&    new(PostHandler => { \*(Aq/\*(Aq => [sub {}], \*(Aq/foo/\*(Aq => [\e&foo]});
.Ve
.IP "StreamHandler" 4
.IX Item "StreamHandler"
If you turn on streaming in any other handler, the request is placed in
streaming mode.  This handler is called, with the usual parameters, when
streaming mode is first entered, and subsequently when each block of data is
flushed to the client.
.Sp
Streaming mode is turned on via the \f(CW$response\fR object:
.Sp
.Vb 1
\&    $response\->streaming(1);
.Ve
.Sp
You deactivate streaming mode with the same object:
.Sp
.Vb 1
\&    $response\->close;
.Ve
.Sp
Content is also sent to the client via the \f(CW$response\fR object:
.Sp
.Vb 1
\&    $response\->send($somedata);
.Ve
.Sp
The output filter is set to POE::Filter::Stream, which passes the data
through unchanged.  If you are doing a multipart/mixed response, you will
have to set up your own headers.
.Sp
Example:
.Sp
.Vb 7
\&    sub new {
\&        .....
\&        POE::Component::Filter::HTTP\->new(
\&                 ContentHandler => { \*(Aq/someurl\*(Aq => sub { $self\->someurl(@_) },
\&                 StreamHandler  => sub { $self\->stream(@_),
\&            );
\&    }
\&
\&    sub someurl {
\&        my($self, $resquest, $response)=@_;
\&        $self\->{todo} = [ .... ];
\&        $response\->streaming(1);
\&        $response\->code(RC_OK);         # you must set up your response header
\&        $response\->content_type(...);
\&
\&        return RC_OK;
\&    }
\&
\&    sub stream {
\&        my($self, $resquest, $response)=@_;
\&
\&        if( @{$self\->{todo}} ) {
\&            $response\->send(shift @{$self\->{todo}});
\&        }
\&        else {
\&            $response\->close;
\&        }
\&    }
.Ve
.Sp
Another example can be found in t/30_stream.t.  The parts dealing with
multipart/mixed are well documented and at the end of the file.
.Sp
\&\s-1NOTE:\s0 Changes in streaming mode are only verified when StreamHandler exits.
So you must either turn streaming off in your StreamHandler, or make sure
that the StreamHandler will be called again.  This last is done by sending
data to the client.  If for some reason you have no data to send, you can
get the same result with \f(CW\*(C`continue\*(C'\fR. Remember that this will also cause the
StreamHandler to be called one more time.
.Sp
.Vb 1
\&    my $aliases=POE::Component::Filter::HTTP\->new( ....);
\&
\&    # and then, when the end of the stream in met
\&    $response\->close;
\&    $response\->continue;
.Ve
.Sp
\&\s-1NOTE:\s0 even when the stream ends, the client connection will be held open if
Keepalive is active.  To force the connection closed, set the \fIConnection\fR
header to \fIclose\fR:
.Sp
.Vb 1
\&    $resquest\->header(Connection => \*(Aqclose\*(Aq);
.Ve
.Sp
\&\fIThis might be a bug.  Are there any cases where we'd want to keep the
connection open after a stream?\fR
.SH "Events"
.IX Header "Events"
The \f(CW\*(C`shutdown\*(C'\fR event may be sent to the component indicating that it
should shut down.  The event may be sent using the return value of the
\&\fI\fInew()\fI\fR method (which is a session id) by either \fIpost()\fRing or
\&\fIcall()\fRing.
.PP
I've experienced some problems with the session not receiving the
event when it gets \fIpost()\fRed so \fIcall()\fR is advised.
.SH "See Also"
.IX Header "See Also"
Please also take a look at HTTP::Response, HTTP::Request,
\&\s-1URI\s0, \s-1POE\s0 and POE::Filter::HTTPD
.SH "TODO"
.IX Header "TODO"
.IP "Document Connection Response and Request objects." 4
.IX Item "Document Connection Response and Request objects."
.PD 0
.IP "Write more tests" 4
.IX Item "Write more tests"
.IP "Add a PoCo::Server::HTTP::Session that matches a http session against poe session using cookies or other state system" 4
.IX Item "Add a PoCo::Server::HTTP::Session that matches a http session against poe session using cookies or other state system"
.IP "Add more options to streaming" 4
.IX Item "Add more options to streaming"
.ie n .IP "Figure out why \fIpost()\fRed ""shutdown"" events don't get received." 4
.el .IP "Figure out why \fIpost()\fRed \f(CWshutdown\fR events don't get received." 4
.IX Item "Figure out why post()ed shutdown events don't get received."
.IP "Probably lots of other \s-1API\s0 changes" 4
.IX Item "Probably lots of other API changes"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Bergman, arthur@contiller.se
.PP
Additional hacking by Philip Gwyn, poe\-at\-pied.nu
.PP
Released under the same terms as \s-1POE\s0.