POE::Component::ServerUserTContributed Perl DocPOE::Component::Server::HTTP(3)NAMEPOE::Component::Server::HTTP - Foundation of a POE HTTP Daemon
SYNOPSIS
use POE::Component::Server::HTTP;
use HTTP::Status;
my $aliases = POE::Component::Server::HTTP->new(
Port => 8000,
ContentHandler => {
'/' => \&handler1,
'/dir/' => sub { ... },
'/file' => sub { ... }
},
Headers => { Server => 'My Server' },
);
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't really needed
POE::Kernel->call($aliases->{tcp}, "shutdown");
DESCRIPTIONPOE::Component::Server::HTTP (PoCo::HTTPD) is a framework for building
custom HTTP servers based on POE. It is loosely modeled on the ideas of
apache and the mod_perl/Apache module.
It is built alot on work done by Gisle Aas on HTTP::* modules and the
URI module which are subclassed.
PoCo::HTTPD lets you register different handler, stacked by directory
that will be run during the cause of the request.
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/.
However, there can be only one ContentHandler and if any handler
installs a ContentHandler that will override the old ContentHandler.
If no handler installs a ContentHandler it will find the closest one
directory wise and use it.
There is also a special StreamHandler which is a coderef that gets
invoked if you have turned on streaming by doing
$response->streaming(1);
Handlers take the $request and $response objects as arguments.
RC_OK
Everything is ok, please continue processing.
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.
RC_WAIT
This is a special handler that suspends the execution of the
handlers. They will be suspended until $response->continue() is
called, this is usefull if you want to do a long request and not
blocck.
The following handlers are available.
TransHandler
TransHandlers are run before the URI has been resolved, giving them
a chance to change the URI. They can therefore not be registred per
directory.
new(TransHandler => [ sub {return RC_OK} ]);
A TransHandler can stop the dispatching of TransHandlers and jump
to the next handler type by specifing RC_DENY;
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.
new(PreHandler => { '/' => [sub {}], '/foo/' => [\&foo]});
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.
new(ContentHandler => { '/' => sub {}, '/foo/' => \&foo});
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. $resquest->is_error and $response->is_error will
return true. Note that "PostHanlder" will still called, but
"TransHandler" and "PreHandler" won't be. It is a map to coderefs
just like ContentHandler is.
PostHandler
These handlers are run after the socket has been flushed.
new(PostHandler => { '/' => [sub {}], '/foo/' => [\&foo]});
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.
Streaming mode is turned on via the $response object:
$response->streaming(1);
You deactivate streaming mode with the same object:
$response->close;
Content is also sent to the client via the $response object:
$response->send($somedata);
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.
Example:
sub new {
.....
POE::Component::Filter::HTTP->new(
ContentHandler => { '/someurl' => 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;
}
}
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.
NOTE: 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 "continue". Remember that this will also cause the
StreamHandler to be called one more time.
my $aliases=POE::Component::Filter::HTTP->new( ....);
# and then, when the end of the stream in met
$response->close;
$response->continue;
NOTE: even when the stream ends, the client connection will be held
open if Keepalive is active. To force the connection closed, set
the Connection header to close:
$resquest->header(Connection => 'close');
This might be a bug. Are there any cases where we'd want to keep
the connection open after a stream?
Events
The "shutdown" event may be sent to the component indicating that it
should shut down. The event may be sent using the return value of the
new() method (which is a session id) by either post()ing or call()ing.
I've experienced some problems with the session not receiving the event
when it gets post()ed so call() is advised.
See Also
Please also take a look at HTTP::Response, HTTP::Request, URI, POE and
POE::Filter::HTTPD
TODO
Document Connection Response and Request objects.
Write more tests
Add a PoCo::Server::HTTP::Session that matches a http session against
poe session using cookies or other state system
Add more options to streaming
Figure out why post()ed "shutdown" events don't get received.
Probably lots of other API changes
AUTHOR
Arthur Bergman, arthur@contiller.se
Additional hacking by Philip Gwyn, poe-at-pied.nu
Released under the same terms as POE.
perl v5.14.1 2006-05-23 POE::Component::Server::HTTP(3)
