/ 
POE-Component-Server-HTTPServer-0.9.2
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::Server::HTTPServer

NAME

POE::Component::Server::HTTPServer - serve HTTP requests

SYNOPSIS

    use POE;
    use POE::Component::Server::HTTPServer;

    my $server = POE::Component::Server::HTTPServer->new();
    $server->port( 8080 );
    $server->handlers( [
                        '/' => new_handler('StaticHandler', './htdocs'),
			'/foo' => \&foo_handler,
			'/bar' => MyBarHandler->new(),
                       ] );
    my $svc = $server->create_server();
    $poe_kernel->run();
    exit 0;

DESCRIPTION

POE::Component::Server::HTTPServer is a POE-based HTTP server. Requests are dispatched based on an ordered list of prefix => handler pairs.

For each pair in the handlers list in sequence, the given handler is invoked if the prefix matches the request path. Each handler can return either a value indicating to continue processing the request, or one telling HTTPServer that request processing is done. Handlers may also modify the request and tell the HTTPServer to restart the dispatch process.

HTTPServer creates a context object for each request (just a hash reference) which it passes to each handler when invoked. Among other standard attributes, this context object contains the HTTP::Request and HTTP::Response objects for the request being processed, as well as the requested path with and without the matched prefix. Handlers may retrieve and set attributes in this context in order to get information and to modify the state of other handlers.

Creational Methods

new( %args )

Creates a new HTTPServer object. The following arguments provide shortcuts for the setter methods of the same name:

port (default: 8080)
handlers (default: none)
log_file (default: httpserver.log)
backstop_handler (default: the NotFoundHandler instance)

For example:

$s = POE::Component::Server::HTTPServer->new(
        port => 8088,
        handlers => [ '/' => new_handler("StaticHandler", "./html") ],
        log_file => "/var/log/myhttp.log",
        backstop_handler => \&my_backstop,
    );

new() does not install a POE component in the kernel. Use create_server() to do this, once the server is appropriately configured.

log_file( $filename ), log_file( )

Returns and (optionally) sets the filename for the request log file. This log lists all requests handled by the server in a format similar to common httpd log format. By default, this file name will be httpserver.log.

port( $port ), port( )

Returns and (optionally) sets the port for the server to listen on. If not explicitly set, the server will listen on port 8080.

handlers( $handlers_listref ), handlers( )

Returns and (optionally) sets the list of request handlers. This accepts and returns an array reference. The list referenced by the return value may be modifed, should you prefer to manipulate the handler list that way. By default, this list is empty.

See "Request Handlers".

backstop_handler( $handler ), backstop_handler( )

Returns and (optionally) sets the backstop handler, the handler invoked if none of the configured handlers finalize the request. If not specified, the server will use the instance of POE::Component::Server::HTTPServer::NotFoundHandler.

Other Methods

create_server( )

Sets up and installs the POE server component in the POE kernel. The newly created component object is returned.

dispatch( $context, $full_request_path )

Dispatch the current request, as set up in the $context. This is intended for redispatching requests to specific server-relative locations. If $full_request_path is not provided, the context attribute fullpath will be used, as set (originally) by the HTTPServer on recieving a new request.

HTTPServer saves a reference to itself in the context under the key dispatcher, allowing you to call this method inside handlers like this:

$context->{dispatcher}->dispatch( $context, $newpath );

Internal Methods

The following methods should be considered private, but may be of interest when subclassing HTTPServer.

_init( @args )

Called by new() to initialize newly created objects.

_get_dispatcher( )

Badly named: returns the coderef for POE::Component::Server::TCP's ClientInput property. This is the coderef that does the request dispatching work.

_request_log( )

Logs a request.

Exported Functions

The following subroutines are exported by default:

new_handler( $short_handler_name, @args )

This is a shortcut for

"POE::Component::Server::HTTPServer::$short_handler_name"->new( @args );

which is significantly less typing for handlers in the default package. This is intended for use when setting the list of handlers.

Request Handlers

Request handlers are used to service incoming requests. Each handler in turn is associated with a relative request URI prefix, and may choose to either finalize the request processing or let it continue.

The prefixes are regular expressions, to be matched against the beginning of the request URI (eg, assume a prepended "^"). Each handler in sequence is invoked if the request matches this prefix.

The handlers themselves may be either an object implementing the interface in POE::Component::Server::HTTPServer, or a subroutine reference. In the first case, HTTPServer will can the object's handle() method, and in the second, HTTPServer will execute the subroutine reference. In both cases, HTTPServer will pass the context object to the method or sub as an argument.

HTTPServer always sets certain attributes in the context before invoking the request:

$context->{request}

The HTTP::Request object holding the request message data.

$context->{response}

The HTTP::Response object to use to build the response message.

$context->{fullpath}

The full relative path of the request URI. This is initially equal to $context->{request}->uri()->path(), but may be modified by request handlers.

$context->{contextpath}

The part of the request path after the prefix which matched for the request handler being invoked.

$context->{dispatcher}

The dispatcher (HTTPServer) processing this request. Request handlers may use this object's dispatch() method to redispatch the request.

Each request handler is passed the context as an argument. Handlers should return either H_CONT, indicating that request processing should continue, or H_FINAL, indicating that the response has been finalized and HTTPServer should stop and return the response message.

There are four standard basic request handlers. The package names for each begin with POE::Component::Server::HTTPServer, but you can use HTTPServer::new_handler() to avoid typing all that. See the documentation for each handler for more detailed information.

NotFoundHandler

Creates and finalizes a 404 Not Found response. If the context attribute error_message is set, it will be included in the response body.

An instance of NotFoundHandler is used by HTTPServer as the backstop handler, so that requests not finalized by any other handler result in a usable response.

StaticHandler

Serves filesystem resources. May also be subclassed to server interpreted resources based on the underlying filesystem.

ParameterParseHandler

Extracts CGI parameters from GET and POST requests, and adds them to the context's param attribute.

BasicAuthenHandler

Performs HTTP basic authentication: interprets request headers and sets the context's basic_username and basic_password attributes. Issues a basic authen challenge response if the request has no auth headers.

OTHER

This module was inspired by POE::Component::Server::HTTP, which deals with request processing in a slightly different manner.

SEE ALSO

POE::Component::Server::HTTPServer::Handler, POE, POE::Component::Server::HTTPServer::Examples

AUTHOR

Greg Fast <gdf@speakeasy.net>

COPYRIGHT

Copyright 2003 Greg Fast.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.