Doc/lib/libsocksvr.tex

   1 \section{Standard Module \module{SocketServer}}
   2 \label{module-SocketServer}
   3 \stmodindex{SocketServer}
   4
   5 The \module{SocketServer} module simplifies the task of writing network
   6 servers.
   7
   8 There are four basic server classes: \class{TCPServer} uses the
   9 Internet TCP protocol, which provides for continuous streams of data
  10 between the client and server.  \class{UDPServer} uses datagrams, which
  11 are discrete packets of information that may arrive out of order or be
  12 lost while in transit.  The more infrequently used
  13 \class{UnixStreamServer} and \class{UnixDatagramServer} classes are
  14 similar, but use \UNIX{} domain sockets; they're not available on
  15 non-\UNIX{} platforms.  For more details on network programming, consult
  16 a book such as W. Richard Steven's \emph{UNIX Network Programming}
  17 or Ralph Davis's \emph{Win32 Network Programming}.
  18
  19 These four classes process requests \dfn{synchronously}; each request
  20 must be completed before the next request can be started.  This isn't
  21 suitable if each request takes a long time to complete, because it
  22 requires a lot of computation, or because it returns a lot of data
  23 which the client is slow to process.  The solution is to create a
  24 separate process or thread to handle each request; the
  25 \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be
  26 used to support asynchronous behaviour.
  27
  28 Creating a server requires several steps.  First, you must create a
  29 request handler class by subclassing the \class{BaseRequestHandler}
  30 class and overriding its \method{handle()} method; this method will
  31 process incoming requests.  Second, you must instantiate one of the
  32 server classes, passing it the server's address and the request
  33 handler class.  Finally, call the \method{handle_request()} or
  34 \method{serve_forever()} method of the server object to process one or
  35 many requests.
  36
  37 Server classes have the same external methods and attributes, no
  38 matter what network protocol they use:
  39
  40 \setindexsubitem{(SocketServer protocol)}
  41
  42 %XXX should data and methods be intermingled, or separate?
  43 % how should the distinction between class and instance variables be
  44 % drawn?
  45
  46 \begin{funcdesc}{fileno}{}
  47 Return an integer file descriptor for the socket on which the server
  48 is listening.  This function is most commonly passed to
  49 \function{select.select()}, to allow monitoring multiple servers in the
  50 same process.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{handle_request}{}
  54 Process a single request.  This function calls the following methods
  55 in order: \method{get_request()}, \method{verify_request()}, and
  56 \method{process_request()}.  If the user-provided \method{handle()}
  57 method of the handler class raises an exception, the server's
  58 \method{handle_error()} method will be called.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{serve_forever}{}
  62 Handle an infinite number of requests.  This simply calls
  63 \method{handle_request()} inside an infinite loop.
  64 \end{funcdesc}
  65
  66 \begin{datadesc}{address_family}
  67 The family of protocols to which the server's socket belongs.
  68 \constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two
  69 possible values.
  70 \end{datadesc}
  71
  72 \begin{datadesc}{RequestHandlerClass}
  73 The user-provided request handler class; an instance of this class is
  74 created for each request.
  75 \end{datadesc}
  76
  77 \begin{datadesc}{server_address}
  78 The address on which the server is listening.  The format of addresses
  79 varies depending on the protocol family; see the documentation for the
  80 socket module for details.  For Internet protocols, this is a tuple
  81 containing a string giving the address, and an integer port number:
  82 \code{('127.0.0.1', 80)}, for example.
  83 \end{datadesc}
  84
  85 \begin{datadesc}{socket}
  86 The socket object on which the server will listen for incoming requests.
  87 \end{datadesc}
  88
  89 % XXX should class variables be covered before instance variables, or
  90 % vice versa?
  91
  92 The server classes support the following class variables:
  93
  94 \begin{datadesc}{request_queue_size}
  95 The size of the request queue.  If it takes a long time to process a
  96 single request, any requests that arrive while the server is busy are
  97 placed into a queue, up to \member{request_queue_size} requests.  Once
  98 the queue is full, further requests from clients will get a
  99 ``Connection denied'' error.  The default value is usually 5, but this
 100 can be overridden by subclasses.
 101 \end{datadesc}
 102
 103 \begin{datadesc}{socket_type}
 104 The type of socket used by the server; \constant{socket.SOCK_STREAM}
 105 and \constant{socket.SOCK_DGRAM} are two possible values.
 106 \end{datadesc}
 107
 108 There are various server methods that can be overridden by subclasses
 109 of base server classes like \class{TCPServer}; these methods aren't
 110 useful to external users of the server object.
 111
 112 % should the default implementations of these be documented, or should
 113 % it be assumed that the user will look at SocketServer.py?
 114
 115 \begin{funcdesc}{finish_request}{}
 116 Actually processes the request by instantiating
 117 \member{RequestHandlerClass} and calling its \method{handle()} method.
 118 \end{funcdesc}
 119
 120 \begin{funcdesc}{get_request}{}
 121 Must accept a request from the socket, and return a 2-tuple containing
 122 the \emph{new} socket object to be used to communicate with the
 123 client, and the client's address.
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{handle_error}{request, client_address}
 127 This function is called if the \member{RequestHandlerClass}'s
 128 \method{handle()} method raises an exception.  The default action is
 129 to print the traceback to standard output and continue handling
 130 further requests.
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{process_request}{request, client_address}
 134 Calls \method{finish_request()} to create an instance of the
 135 \member{RequestHandlerClass}.  If desired, this function can create a
 136 new process or thread to handle the request; the \class{ForkingMixIn}
 137 and \class{ThreadingMixIn} classes do this.
 138 \end{funcdesc}
 139
 140 % Is there any point in documenting the following two functions?
 141 % What would the purpose of overriding them be: initializing server
 142 % instance variables, adding new network families?
 143
 144 \begin{funcdesc}{server_activate}{}
 145 Called by the server's constructor to activate the server.
 146 May be overridden.
 147 \end{funcdesc}
 148
 149 \begin{funcdesc}{server_bind}{}
 150 Called by the server's constructor to bind the socket to the desired
 151 address.  May be overridden.
 152 \end{funcdesc}
 153
 154 \begin{funcdesc}{verify_request}{request, client_address}
 155 Must return a Boolean value; if the value is true, the request will be
 156 processed, and if it's false, the request will be denied.
 157 This function can be overridden to implement access controls for a server.
 158 The default implementation always return true.
 159 \end{funcdesc}
 160
 161 The request handler class must define a new \method{handle()} method,
 162 and can override any of the following methods.  A new instance is
 163 created for each request.
 164
 165 \begin{funcdesc}{finish}{}
 166 Called after the \method{handle()} method to perform any clean-up
 167 actions required.  The default implementation does nothing.  If
 168 \method{setup()} or \method{handle()} raise an exception, this
 169 function will not be called.
 170 \end{funcdesc}
 171
 172 \begin{funcdesc}{handle}{}
 173 This function must do all the work required to service a request.
 174 Several instance attributes are available to it; the request is
 175 available as \member{self.request}; the client address as
 176 \member{self.client_request}; and the server instance as
 177 \member{self.server}, in case it needs access to per-server
 178 information.
 179
 180 The type of \member{self.request} is different for datagram or stream
 181 services.  For stream services, \member{self.request} is a socket
 182 object; for datagram services, \member{self.request} is a string.
 183 However, this can be hidden by using the mix-in request handler
 184 classes
 185 \class{StreamRequestHandler} or \class{DatagramRequestHandler}, which
 186 override the \method{setup()} and \method{finish()} methods, and
 187 provides \member{self.rfile} and \member{self.wfile} attributes.
 188 \member{self.rfile} and \member{self.wfile} can be read or written,
 189 respectively, to get the request data or return data to the client.
 190 \end{funcdesc}
 191
 192 \begin{funcdesc}{setup}{}
 193 Called before the \method{handle()} method to perform any
 194 initialization actions required.  The default implementation does
 195 nothing.
 196 \end{funcdesc}