\input{libsocksvr}

\input{libsocksvr}

\section{Standard Module \sectcode{SocketServer}}

\stmodindex{SocketServer}

The \code{SocketServer} module simplifies the task of writing network

servers.

There are four basic server classes: \code{TCPServer} uses the

Internet TCP protocol, which provides for continuous streams of data

between the client and server. \code{UDPServer} uses datagrams, which

are discrete packets of information that may arrive out of order or be

lost while in transit. The more infrequently used

\code{UnixStreamServer} and \code{UnixDatagramServer} classes are

similar, but use Unix domain sockets; they're not available on

non-Unix platforms. For more details on network programming, consult

a book such as W. Richard Steven's \emph{Unix Network Programming}_ or

XXX (a Windows equivalent).

These four classes process requests \dfn{synchronously}; each request

must be completed before the next request can be started. This isn't

suitable if each request takes a long time to complete, because it

requires a lot of computation, or because it returns a lot of data

which the client is slow to process. The solution is to create a

separate process or thread to handle each request; the

\code{ForkingMixIn} and \code{ThreadingMixIn} mix-in classes can be

used to support asynchronous behaviour.

Creating a server requires several steps. First, you must create a

request handler class by subclassing the \code{BaseRequestHandler}

class and overriding its \code{handle()} method; this method will

process incoming requests. Second, you must instantiate one of the

server classes, passing it the server's address and the request

handler class. Finally, call the \code{handle_request()} or

\code{serve_forever()} method of the server object to process one or

many requests.

Server classes have the same external methods and attributes, no

matter what network protocol they use:

\begin{funcdesc}{fileno}{}

Return an integer file descriptor for the socket on which the server

is listening. This function is most commonly passed to

\code{select.select()}, to allow monitoring multiple servers in the

same process.

\end{funcdesc}

\begin{funcdesc}{handle_request}{}

Process a single request. This function calls the following methods

in order: \code{get_request()}, \code{verify_request()}, and

\code{process_request()}. If the user-provided \code{handle()} method

of the handler class raises an exception, the server's

\code{handle_error()} method will be called.

\end{funcdesc}

\begin{funcdesc}{serve_forever}{}

Handle an infinite number of requests. This simply calls

\code{handle_request()} inside an infinite loop.

\end{funcdesc}

\begin{datadesc}{address_family}

The family of protocols to which the server's socket belongs.

\code{socket.AF_INET} and \code{socket.AF_UNIX} are two possible values.

\end{datadesc}

\begin{datadesc}{RequestHandlerClass}

The user-provided request handler class; an instance of this class is

created for each request.

\end{datadesc}

\begin{datadesc}{server_address}

The address on which the server is listening. The format of addresses

varies depending on the protocol family; see the documentation for the

socket module for details. For Internet protocols, this is a tuple

containing a string giving the address, and an integer port number:

\code{('127.0.0.1', 80)}, for example.

\end{datadesc}

\begin{datadesc}{socket}

The socket object on which the server will listen for incoming requests.

\end{datadesc}

The server classes support the following class variables:

\begin{datadesc}{request_queue_size}

The size of the request queue. If it takes a long time to process a

single request, any requests that arrive while the server is busy are

placed into a queue, up to \code{request_queue_size} requests. Once

the queue is full, further requests from clients will get a

``Connection denied'' error. The default value is usually 5, but this

can be overridden by subclasses.

\end{datadesc}

\begin{datadesc}{socket_type}

The type of socket used by the server; \code{socket.SOCK_STREAM} and

\code{socket.SOCK_DGRAM} are two possible values.

\end{datadesc}

There are various server methods that can be overridden by subclasses

of base server classes like \code{TCPServer}; these methods aren't

useful to external users of the server object.

\begin{funcdesc}{finish_request}{}

Actually processes the request by instantiating

\code{RequestHandlerClass} and calling its \code{handle()} method.

\end{funcdesc}

\begin{funcdesc}{get_request}{}

Must accept a request from the socket, and return a 2-tuple containing

the \emph{new} socket object to be used to communicate with the

client, and the client's address.

\end{funcdesc}

\begin{funcdesc}{handle_error}{request\, client_address}

This function is called if the \code{RequestHandlerClass}'s

\code{handle} method raises an exception. The default action is to print

the traceback to standard output and continue handling further requests.

\end{funcdesc}

\begin{funcdesc}{process_request}{request\, client_address}

Calls \code{finish_request()} to create an instance of the

\code{RequestHandlerClass}. If desired, this function can create a new

process or thread to handle the request; the \code{ForkingMixIn} and

\code{ThreadingMixIn} classes do this.

\end{funcdesc}

\begin{funcdesc}{server_activate}{}

Called by the server's constructor to activate the server.

May be overridden.

\end{funcdesc}

\begin{funcdesc}{server_bind}{}

Called by the server's constructor to bind the socket to the desired

address. May be overridden.

\end{funcdesc}

\begin{funcdesc}{verify_request}{request\, client_address}

Must return a Boolean value; if the value is true, the request will be

processed, and if it's false, the request will be denied.

This function can be overridden to implement access controls for a server.

The default implementation always return true.

\end{funcdesc}

The request handler class must define a new \code{handle} method, and

can override any of the following methods. A new instance is created

for each request.

\begin{funcdesc}{finish}{}

Called after the \code{handle} method to perform any clean-up actions

required. The default implementation does nothing. If \code{setup()}

or \code{handle()} raise an exception, this function will not be called.

\end{funcdesc}

\begin{funcdesc}{handle}{}

This function must do all the work required to service a request.

Several instance attributes are available to it; the request is

available as \code{self.request}; the client address as

\code{self.client_request}; and the server instance as \code{self.server}, in

case it needs access to per-server information.

The type of \code{self.request} is different for datagram or stream

services. For stream services, \code{self.request} is a socket

object; for datagram services, \code{self.request} is a string.

However, this can be hidden by using the mix-in request handler

classes

\code{StreamRequestHandler} or \code{DatagramRequestHandler}, which

override the \code{setup} and \code{finish} methods, and provides

\code{self.rfile} and \code{self.wfile} attributes. \code{self.rfile}

and \code{self.wfile} can be read or written, respectively, to get the

request data or return data to the client.

\end{funcdesc}

\begin{funcdesc}{setup}{}

Called before the \code{handle} method to perform any initialization

actions required. The default implementation does nothing.

\end{funcdesc}