NAME
POE::Component::Server::HTTP - Foundation of a POE HTTP Daemon
SYNOPSIS
use POE::Component::Server::HTTP;
use HTTP::Status;
$httpd = POE::Component::Server::HTTP->new(
Port => 8000,
ContentHandler => { '/' => \&handler },
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($httpd, "shutdown");
DESCRIPTION
POE::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/ will first push the handlers of / then of /foo/ then of /foo/bar/ and lastly /foo/bar/baz/,
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});
- PostHandler
-
These handlers are run after the socket has been flushed.
new(PostHandler => { '/' => [sub {}], '/foo/' => [\&foo]});
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 tests
- 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
Released under the same terms as POE.