HTTP::AppServer - Pure-Perl web application server framework
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;
HTTP::AppServer was created because a stripped down Perl based web server was needed that is extendable and really simple to use.
To create a server instance, call the new() class method of HTTP::AppServer, e.g.:
my $server = HTTP::AppServer->new( StartBackground => 0, ServerPort => 3000 );
Defines if the server should be startet in background mode or not. Default is to NOT start in background.
Defines the local port the server listens to. Default is to listen at port 3000.
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...
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.
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).
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.
See HTTP::AppServer::Plugin
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.
These plugins are delivered with HTTP::AppServer itself:
See HTTP::AppServer::Plugin::HTTPAuth for documentation.
See HTTP::AppServer::Plugin::CustomError for documentation.
See for HTTP::AppServer::Plugin::Database documentation.
See for HTTP::AppServer::Plugin::FileRetriever documentation.
See for HTTP::AppServer::Plugin::PlainHTML documentation.
HTTP::Server::Simple::CGI
Tom Kirchner, <tom@tkirchner.com>
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.
To install HTTP::AppServer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::AppServer
CPAN shell
perl -MCPAN -e shell install HTTP::AppServer
For more information on module installation, please visit the detailed CPAN module installation guide.