/ 
HTTP-AppServer-0.03
River stage zero No dependents
/ HTTP::AppServer

NAME

HTTP::AppServer - Pure-Perl web application server framework

SYNOPSIS

  use HTTP::AppServer;
  
  # create server instance at localhost:3000
  my $server = HTTP::AppServer->new( StartBackground => 0, ServerPort => 3000 );
 
  # alias URL
  $server->handle('^\/$', '/index.html');

  # load plugin for simple file retrieving from a document root
  $server->plugin('FileRetriever', DocRoot => '/path/to/docroot');
	
  # start server
  $server->start;

DESCRIPTION

HTTP::AppServer was created because a stripped down Perl based web server was needed that is extendable and really simple to use.

Creating server

To create a server instance, call the new() class method of HTTP::AppServer, e.g.:

my $server = HTTP::AppServer->new( StartBackground => 0, ServerPort => 3000 );

Constructor options

StartBackground => 1/0

Defines if the server should be startet in background mode or not. Default is to NOT start in background.

ServerPort => Port

Defines the local port the server listens to. Default is to listen at port 3000.

Installing URL handlers

The main purpose of having a webserver is to make it able to bind URLs to server side logic or content. To install such a binding in your instance of HTTP::AppServer, you can use the handle() method.

The URL is given as a Perl regular expression, e.g.

'^\/hi'

matches all URLs starting with '/hi' and anything coming after that.

You can either install a perl code reference that handles the URL:

$server->handle('^\/hello$', sub {
  my ($server, $cgi) = @_;
  print "HTTP/1.0 200 Ok\r\n";
  print $cgi->header('text/html');
  print "Hello, visitor!";
});

Or you can

$server->handle('^\/$', '/index.html');

In this example: whenever a URL matches a '/' at the beginning, the URL is transformed into '/index.html' and HTTP::AppServer tries to find a handler that handles that URL.

In case of a code reference handler (first example) the parameters passed to the code reference are first the serve instance and second the cgi object (instance of CGI). The second comes in handy when creating HTTP headers and such.

Additional parameters are the groups defined in the regular expression that matches the URL which brings us to the variable URL parts...

Variable URL parts

Suppose you want to match a URL that contains a variable ID of some sort and another part that is variable. You could do it this way:

$server->handle('^\/(a|b|c)\/(\d+)', sub {
  my ($server, $cgi, $category, $id) = @_;
  # ...
});

As you can see, the two groups in the regular expression are passed as additional parameters to the code reference.

Multimatching vs. Singlematching

Each called handler (code reference) can tell HTTP::AppServer if it should continue looking for another matching handler or not. To make HTTP::AppServer continue searching after the handler, the handler has to return 0. If anything else is returned, HTTP::AppServer tries to find another matching handler.

A handler is executed once at most (even if it matches multiple times).

Using plugins

Use the plugin() method to load and configure a plugin, e.g.:

$server->plugin('FileRetriever', DocRoot => '/path/to/docroot');

The first parameter is the name of the plugin, a class in the HTTP::AppServer::Plugin:: namespace. After that configuration options follow, see plugin documentation for details on that.

Plugin development

See HTTP::AppServer::Plugin

Handler precedence

When HTTP::AppServer tries to find a handler for an URL it goes through the list of installed handlers (either by user or a plugin) and the first that matches, is used.

As described above, each handler can tell if he wants the output beeing delivered to the client OR continue find another handler.

Core plugins

These plugins are delivered with HTTP::AppServer itself:

HTTP::AppServer::Plugin::HTTPAuth

See HTTP::AppServer::Plugin::HTTPAuth for documentation.

HTTP::AppServer::Plugin::CustomError

See HTTP::AppServer::Plugin::CustomError for documentation.

HTTP::AppServer::Plugin::Database

See for HTTP::AppServer::Plugin::Database documentation.

HTTP::AppServer::Plugin::FileRetriever

See for HTTP::AppServer::Plugin::FileRetriever documentation.

HTTP::AppServer::Plugin::PlainHTML

See for HTTP::AppServer::Plugin::PlainHTML documentation.

SEE ALSO

HTTP::Server::Simple::CGI

AUTHOR

Tom Kirchner, <tom@tkirchner.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Tom Kirchner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.