PSP::Socket - Socket to process Web requests.

- NAME
- SYNOPSIS
- DESCRIPTION

- METHODS

- $listener = PSP::Socket->new( LocalPort=>9090 );
- $listener->initenv();
- $listener->run();
- $listener->poll();
- $client->accepted( $from, ... );
- $client->error( ... );
- $client->main( ... );
- $client->parse_request();
- $client->characterise( $from $env );
- $client->document_root( $env );
- $client->params();
- $client->cookies();
- $client->authenticate( $realm );
- $client->divert();
- $client->DESTROY();

# 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.