PSP::Socket - Socket to process Web requests.


NAME

PSP::Socket - Socket to process Web requests.


SYNOPSIS

Subclass of IO::Socket::INET to simulate CGI interface without a fork(). A web application can subclass this package and request will be served by the main() method of that class. This method can be coded as you would a noraml CGI script. A script ``../exmaple.pl'' is provided with this distribution demonstrates this with a simple implementation of ``mastermind''.


DESCRIPTION

This class accepts connections from browser clients on the specified LocalPort and reqdirects STDIN and STDOUT to the client to allow the request to be precessed without a fork in a manner compatabile with the Apache ``CGI'' interface. Requests are expected to be processed by overriding the ``main()'' method of a subclass of this package.

METHODS

$listener = PSP::Socket->new( LocalPort=>9090 );

Create a new instance of a Web server for accepting and serving connections from browser clients. This will generally be called for a subclass of PSP::Socket

$listener->initenv();

Setup unchanging environment varaiable which are part of the CGI interface which identify the server software, port number etc.

$listener->run();

Run the Web serverm polling for new connections, accepting them, parsing their requests and serveing them by calling the main() method of listeners package.

$listener->poll();

Poll for a connection from a browser by calling ``accept()''. This would generally block unless the socket has been fcntled to be O_NONBLOCK or the socket was opened with a zero (or near zero to work around a restriction in IO::Socket) timeout. Calls ``accepted()'' on the client socket returned for it to be processed.

$client->accepted( $from, ... );

A new connection has arrived from a client and should be processed. The request header is parsed by ``parse_request()'' and STDIN/STDOUT redirected to be connected directly to the client browser (so called ``NPH'' or non-parsed-header operation). Method main is then called on the socket to process the request.

$client->error( ... );

Create a Web page reporting an server error to the client browser.

$client->main( ... );

This is the method which should actually process the request and should be overidden in a subclass of thispackage to do something useful.

$client->parse_request();

Parse the incomming header from the browser client and setup the environment varaiables specified in the CGI ``common gateway interface'' to allow modules such as ``CGI.pm'' to operate as the would from a CGI script.

$client->characterise( $from $env );

As a new user connects, record any refering page and the browser type. This is used to determine which browsers to support.

$client->document_root( $env );

Determine the root directory for documents for the server that the client connected to. A Web servers host can be connected to using a number of different names and this information is recorded in the ``Host:'' request attribute sent from the client browser. This can be used to switch between a number document driectories to create a ``Virtual hosts''. Create a driectory with the name of the vritual host and it will be used for that web site.

$client->params();

An implementation of parameter parsing to demystify it a little but in general it is best to use CGI.pm.

$client->cookies();

Returns a hash of cookies again to show how it is done.

$client->authenticate( $realm );

The last utility routine which requires the user to login to a page for which this function is called. The resulting login is unencoded and returned to the callee. If this function returns an empty array a ``401 authentification required'' header has been sent to the browser to popup a login panel for the ``realm'' and thepage must retry.

$client->divert();

connects STDIN and STDOUT to the socket connected to the client browser so that output sent using ``print()'' will find its way to the browser.

$client->DESTROY();

called when the client socket closes to unrediect STDIN and STDOUT so the the connect to the client is closed correctly.

 PSP::Socket - Socket to process Web requests.