DESCRIPTION

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

_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

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

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.