/ 
POE-Component-Server-SimpleContent-0.99
River stage one • 3 direct dependents • 3 total dependents
/ POE::Component::Server::SimpleContent

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.