NAME

POE::Component::Server::SimpleContent - The easy way to serve web content with POE::Component::Server::SimpleHTTP.

SYNOPSIS

            

              
              
 # A simple web server 
 use POE qw(Component::Server::SimpleHTTP Component::Server::SimpleContent);
 my ($content) = POE::Component::Server::SimpleContent->spawn( root_dir => '/blah/blah/path' );
 POE::Component::Server::SimpleHTTP->new(
ALIAS => 'httpd',
ADDRESS => '6.6.6.6',
PORT => 8080,
HANDLERS => [
        {
          DIR => '.*',
          EVENT => 'request',
          SESSION => $content->session_id(),
        },
],
 );
 $poe_kernel->run();
 exit 0;
            
          

DESCRIPTION

POE::Component::Server::SimpleContent is a companion POE component to POE::Component::Server::SimpleHTTP ( though it can be used standalone ), that provides a virtualised filesystem for serving web content. It uses Filesys::Virtual::Plain to manage the virtual file system.

As demonstrated in the SYNOPSIS, POE::Component::Server::SimpleContent integrates with POE::Component::Server::SimpleHTTP. General usage involves setting up your own custom handlers *before* a catchall handler which will route HTTP requests to SimpleContent.

The component generates a minimal 404 error page as a response if the requested URL doesn't not exist in the virtual filesystem. It will generate a minimal 403 forbidden page if 'auto_index' is set to 0 and a requested directory doesn't have an 'index_file'

Directory indexing is supported by default, though don't expect anything really fancy.

CONSTRUCTOR

spawn

Requires one mandatory argument, 'root_dir': the file system path which will become the root of the virtual filesystem. Returns an object on success. Optional arguments are:

            

              
              
alias      - the POE::Kernel alias to set for the component's session;
options    - a hashref of POE::Session options to pass to the component's session;
index_file - the filename that will be used if someone specifies a directory path,
      default is 'index.html';
auto_index - whether directory indexing is performed, default is 1;
            
          

Example:

            

              
              
my ($content) = POE::Component::Server::SimpleContent->spawn(
root_dir   => '/blah/blah/path',
options    => { trace => 1 },
index_file => 'default.htm',
auto_index  => 0,
);
            
          

METHODS

session_id

Takes no arguments. Returns the POE::Session ID of the component's session.

            

              
              
my ($session_id) = $content->session_id();
            
          

shutdown

Takes no arguments, shuts down the component's session.

            

              
              
$content->shutdown();
            
          

request

Requires two arguments, a HTTP::Request object and HTTP::Response object. See OUTPUT for what is returned by this method.

            

              
              
$content->request( $request_obj, $response_obj );
            
          

auto_index

No parameter specified returns whether 'auto_index' is enabled or not. If a true or false value is specified, enables or disables 'auto_index', respectively.

index_file

No parameter specified, returns the current setting of 'index_file'. If a parameter is specified, sets 'index_file' to that given value.

INPUT

These are the events that the component will accept.

request

Requires two arguments, a HTTP::Request object and HTTP::Response object. See OUTPUT for what is returned by this method.

            

              
              
$kernel->post( $content->session_id() => request => $request_obj => $response_obj );
            
          

shutdown

Takes no arguments, shuts down the component's session.

            

              
              
$kernel->post( $content->session_id() => 'shutdown' );
            
          

OUTPUT

The component returns the following event to the sessions that issued a 'request', either via the object API or the session API. The event is 'DONE' to maintain compatibility with POE::Component::Server::SimpleHTTP.

DONE

ARG0 will be a HTTP::Response object.

CAVEATS

This module is designed for serving small content, ie. HTML files and jpegs/png/gifs. There is a good chance that the component might block when atttempting to serve larger content, such as MP3s, etc.

TODO

Use POE::Wheel::Run to provide full non-blocking content serving.

More comprehensive HTTP error handling, with the ability to specify custom 404 error pages.

More 'fancy' directory listing.

AUTHOR

Chris 'BinGOs' Williams

KUDOS

Apocal for writing POE::Component::Server::SimpleHTTP.

Xantus for Filesys::Virtual::Plain

Those cheeky chaps at #PoE @ irc.perl.org for ever helpful suggestions.

SEE ALSO

HTTP::Request, HTTP::Request, POE::Component::Server::SimpleHTTP, POE.

cpanm POE::Component::Server::SimpleContent

perl -MCPAN -e shell
install POE::Component::Server::SimpleContent