| Name : perl-NetServer-Generic
| |
| Version : 1.03
| Vendor : obs://build_opensuse_org/devel:languages:perl
|
| Release : 1.57
| Date : 2024-08-05 18:04:36
|
| Group : Development/Libraries/Perl
| Source RPM : perl-NetServer-Generic-1.03-1.57.src.rpm
|
| Size : 0.07 MB
| |
| Packager : (none)
| |
| Summary : 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:
* port
The port to listen on.
* hostname
The local address to bind to. If no address is specified, listens for any
connection on the designated port.
* listen
Queue size for listen.
* proto
Protocol we\'re listening to (defaults to tcp)
* timeout
Timeout value (see IO::Socket::INET)
* 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.
* 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).
* 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).
* 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.
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\
\"; # 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 (AATTpath) = split(\"/\", $f);
my ($buff, $acc) = \"\";
shift AATTpath;
while ($buff = shift AATTpath) {
my ($tmp) = shift AATTpath;
if ($tmp ne \'..\') {
unshift AATTpath, $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\
\";
my ($in) = new IO::File();
if ($in->open(\"< $getfile\") ) {
$in->autoflush(1);
print STDOUT \"Content-type: text/html\
\
\";
while (defined ($line = < $in>)) {
print STDOUT $line;
}
} else {
print STDOUT \"404: File not found\
\
\";
}
}
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\
\";
$foo->run();
exit 0;
|
RPM found in directory: /packages/linux-pbone/ftp5.gwdg.de/pub/opensuse/repositories/devel:/languages:/perl:/CPAN-N/openSUSE_Tumbleweed/noarch |
