skip to main content

Package Information for perl-NetServer-Generic 1.03-1

Name: perl-NetServer-Generic Vendor: Charlie Stross <charle@antipope.org>
Version: 1.03 Build Date: Thu Feb 22 14:25:21 2007
Release: 1 Build Host: hamnavoe.inf.ed.ac.uk
Group: Applications/CPAN Source: perl-NetServer-Generic-1.03-1.src.rpm
Size: 75364 License: Artistic
Packager: Arix International <cpan2rpm-AT-arix.com> Arch: noarch
Summary: NetServer-Generic - generic TCP/IP server class
Description:  
"NetServer::Generic" provides a (very) simple server daemon for TCP/IP
processes. It is intended to free the programmer from having to think
too hard about networking issues so that they can concentrate on
doing something useful.

The "NetServer::Generic" object accepts the following methods, which
configure various aspects of the new server:

=over 4

=item port

The port to listen on.

=item hostname

The local address to bind to. If no address is specified, listens for
any connection on the designated port.

=item listen

Queue size for listen.

=item proto

Protocol we're listening to (defaults to tcp)

=item timeout

Timeout value (see IO::Socket::INET)

=item allowed

list of IP addresses or hostnames that are explicitly allowed to connect
to the server. If empty, the default policy is to allow connections from
anyone not in the 'forbidden' list.

NOTE: IP addresses or hostnames may be specified as perl regular
expressions; for example 154\.153\.4\..* matches any IP address
beginning with '154.153.4.';
.*antipope\.org matches any hostname in the antipope.org domain.

=item forbidden

list of IP addresses or hostnames that are refused permission to
connect to the server. If empty, the default policy is to refuse
connections from anyone not in the 'allowed' list (unless the
allowed list is empty, in which case anyone may connect).

=item callback

Coderef to a subroutine which handles incoming connections (called
with one parameter -- a "NetServer::Generic" object which can be used
to shut down the session).

=item mode

Can be one of forking, select, select_fast, client,
threaded, or prefork.

By default, forking mode is selected.

forking mode is selected, the server handles requests by forking a
child process to service them. If select mode is selected, the server
uses the "IO::Select" class to implement a simple non-forking server.

The select-based server may block on i/o on a heavily-loaded system. If
you need to do non-blocking i/o you should look at NetServer::FastSelect.

The client mode is special; it indicates that rather than sitting
around waiting for an incoming connection, the server is itself a
TCP/IP client. In client mode, "hostname" is the remote host to
connect to and "port" is the remote port to open. The callback
routine is used, as elsewhere, but it should be written as for a
client -- i.e. it should issue a request or command, then read.
An additional method exists for client mode: "trigger". "trigger"
expects a coderef as a parameter. This coderef is executed
before the client-mode server spawns a child; if it returns a non-zero
value the child is forked and opens a client connection to the target
host, otherwise the server exits. The trigger method may be used to
sleep for a random interval then return 1 (so that repeated clients
are spawned at random intervals), or fork several children (on a one-
time-only basis) then work as above (so that several clients poke at
the target server on a random basis). The default trigger method
returns 1 immediately the first time it is called, then returns 0 --
this means that the client makes a single connection to the target
host, invokes the callback routine, then exits. (See the test examples
which come with this module for examples of how to use client mode.)

Note that client mode relies on the fork() system call.

The threaded mode indicates that multithreading will be used to
service requests. This feature requires Perl 5.005 or higher and a
native threads library to run, so it's not 100% portable). Moreover,
it's unreliable! Don't use this mode unless you're prepared to do some
debugging.

The prefork mode indicates that the server will bind to the
designated port, then fork repeatedly up to $start_servers times
(where "start_servers" is a scalar parameter to "NetServer::Generic").
Each child then enters a select-based loop. (i.e. run_select), but exits
after handling $server_lifespan transactions (where "server_lifespan"
is another parameter to "NetServer::Generic"). Every time a child
handles a transaction it writes its PID and generation number down a pipe
to the parent process, with a message when it exits. The parent keeps
track of how many servers are in use and fires up extra children (up to
$max_servers) if the number in use leaves less than $min_spare_servers
free. See the example preforked-shttpd for a minimal HTTP 0.9 server
implemented using the prefork mode.


=back

Of these, the "callback" method is most important; it specifies
a reference to a subroutine which effectively does whatever the
server does.

A callback subroutine is a normal Perl subroutine. It is invoked
with STDIN and STDOUT attached to an "IO::Socket::INET" object,
so that reads from STDIN get information from the client, and writes
to STDOUT send information to the client. Note that both STDIN and
STDOUT are unbuffered. In addition, a "NetServer::Generic" object is
passed as an argument (but the "callback" is free to ignore it).

Your server reads and writes data via the socket as if it is the
standard input and standard output filehandles; for example:

while (defined ($tmp = <STDIN>)) { # read a line from the socket

print STDOUT "You said: $tmp\n"; # print something to the socket

(See "IO::Handle" and "IO::Socket" for more information on this.)

If you're not familiar with sockets, don't get too fresh and try to
close or seek on STDIN or STDOUT; just treat them like a file.

The server object is not strictly necessary in the callback, but comes
in handy: you can shut down the server completely by calling the
"quit()" method.

When writing a callback subroutine, remember to define some condition under
which you return!

Here's a slightly more complex server example:













sub url_to_file($) {

my ($u) = shift ; # incoming URL fragment from GET request
my ($f) = ""; # file pathname to return
my ($htbase) = "/usr/local/etc/httpd/docs/";
my ($htdefault) = "index.html";
chop $u;
if ($u eq "/") {
$f = $htbase . $htdefault;
return $f;
} else {
if ($u =~ m|^/.+|) {
$f = $htbase; chop $f;
$f .= $u;
} elsif ($u =~ m|[^/]+|) {
$f = $htbase . $u;
}
if ($u =~ m|.+/$|) {
$f .= $htdefault;
}
if ($f =~ /\.\./) {
my (@path) = split("/", $f);
my ($buff, $acc) = "";
shift @path;
while ($buff = shift @path) {
my ($tmp) = shift @path;
if ($tmp ne '..') {
unshift @path, $tmp;
$acc .= "/$buff";
}
}
$f = $acc;
}
}
return $f;
}

my ($http) = sub {
my ($fh) = shift ;
while (defined ($tmp = <STDIN>)) {
chomp $tmp;
if ($tmp =~ /^GET\s+(.*)$/i) {
$getfile = $1;
$getfile = url_to_file($getfile);
print STDERR "Sending $getfile\n";
my ($in) = new IO::File();
if ($in->open("<$getfile") ) {
$in->autoflush(1);
print STDOUT "Content-type: text/html\n\n";
while (defined ($line = <$in>)) {
print STDOUT $line;
}
} else {
print STDOUT "404: File not found\n\n";
}
}
return 0;
}
};



my (%config) = ("port" => 9000,
"callback" => $http,
"hostname" => "public.antipope.org");

my ($allowed) = ['.*antipope\.org',
'.*localhost.*'];

my ($forbidden) = [ '194\.205\.10\.2'];

my ($foo) = new Server(%config); # create new http server bound to port

$foo->allowed($allowed); # who is allowed to connect to us
$foo->forbidden($forbidden); # who is refused access
print "Starting http server on port 9000\n";
$foo->run();
exit 0;

Documentation Files

Click on a link to view the documentation file, pod files will be automatically converted into html.