NAME

       POE::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");

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