Lib/dos-8x3/socketse.py

   1 """Generic socket server classes.
   2
   3 This module tries to capture the various aspects of defining a server:
   4
   5 - address family:
   6         - AF_INET: IP (Internet Protocol) sockets (default)
   7         - AF_UNIX: Unix domain sockets
   8         - others, e.g. AF_DECNET are conceivable (see <socket.h>
   9 - socket type:
  10         - SOCK_STREAM (reliable stream, e.g. TCP)
  11         - SOCK_DGRAM (datagrams, e.g. UDP)
  12 - client address verification before further looking at the request
  13         (This is actually a hook for any processing that needs to look
  14          at the request before anything else, e.g. logging)
  15 - how to handle multiple requests:
  16         - synchronous (one request is handled at a time)
  17         - forking (each request is handled by a new process)
  18         - threading (each request is handled by a new thread)
  19
  20 The classes in this module favor the server type that is simplest to
  21 write: a synchronous TCP/IP server.  This is bad class design, but
  22 save some typing.  (There's also the issue that a deep class hierarchy
  23 slows down method lookups.)
  24
  25 There are four classes in an inheritance diagram that represent
  26 synchronous servers of four types:
  27
  28         +-----------+        +------------------+
  29         | TCPServer |------->| UnixStreamServer |
  30         +-----------+        +------------------+
  31               |
  32               v
  33         +-----------+        +--------------------+
  34         | UDPServer |------->| UnixDatagramServer |
  35         +-----------+        +--------------------+
  36
  37 Note that UnixDatagramServer derives from UDPServer, not from
  38 UnixStreamServer -- the only difference between an IP and a Unix
  39 stream server is the address family, which is simply repeated in both
  40 unix server classes.
  41
  42 Forking and threading versions of each type of server can be created
  43 using the ForkingServer and ThreadingServer mix-in classes.  For
  44 instance, a threading UDP server class is created as follows:
  45
  46         class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
  47
  48 The Mix-in class must come first, since it overrides a method defined
  49 in UDPServer!
  50
  51 To implement a service, you must derive a class from
  52 BaseRequestHandler and redefine its handle() method.  You can then run
  53 various versions of the service by combining one of the server classes
  54 with your request handler class.
  55
  56 The request handler class must be different for datagram or stream
  57 services.  This can be hidden by using the mix-in request handler
  58 classes StreamRequestHandler or DatagramRequestHandler.
  59
  60 Of course, you still have to use your head!
  61
  62 For instance, it makes no sense to use a forking server if the service
  63 contains state in memory that can be modified by requests (since the
  64 modifications in the child process would never reach the initial state
  65 kept in the parent process and passed to each child).  In this case,
  66 you can use a threading server, but you will probably have to use
  67 locks to avoid two requests that come in nearly simultaneous to apply
  68 conflicting changes to the server state.
  69
  70 On the other hand, if you are building e.g. an HTTP server, where all
  71 data is stored externally (e.g. in the file system), a synchronous
  72 class will essentially render the service "deaf" while one request is
  73 being handled -- which may be for a very long time if a client is slow
  74 to reqd all the data it has requested.  Here a threading or forking
  75 server is appropriate.
  76
  77 In some cases, it may be appropriate to process part of a request
  78 synchronously, but to finish processing in a forked child depending on
  79 the request data.  This can be implemented by using a synchronous
  80 server and doing an explicit fork in the request handler class's
  81 handle() method.
  82
  83 Another approach to handling multiple simultaneous requests in an
  84 environment that supports neither threads nor fork (or where these are
  85 too expensive or inappropriate for the service) is to maintain an
  86 explicit table of partially finished requests and to use select() to
  87 decide which request to work on next (or whether to handle a new
  88 incoming request).  This is particularly important for stream services
  89 where each client can potentially be connected for a long time (if
  90 threads or subprocesses can't be used).
  91
  92 Future work:
  93 - Standard classes for Sun RPC (which uses either UDP or TCP)
  94 - Standard mix-in classes to implement various authentication
  95   and encryption schemes
  96 - Standard framework for select-based multiplexing
  97
  98 XXX Open problems:
  99 - What to do with out-of-band data?
 100
 101 """
 102
 103
 104 __version__ = "0.2"
 105
 106
 107 import socket
 108 import sys
 109 import os
 110
 111
 112 class TCPServer:
 113
 114     """Base class for various socket-based server classes.
 115
 116     Defaults to synchronous IP stream (i.e., TCP).
 117
 118     Methods for the caller:
 119
 120     - __init__(server_address, RequestHandlerClass)
 121     - serve_forever()
 122     - handle_request()  # if you don't use serve_forever()
 123     - fileno() -> int   # for select()
 124
 125     Methods that may be overridden:
 126
 127     - server_bind()
 128     - server_activate()
 129     - get_request() -> request, client_address
 130     - verify_request(request, client_address)
 131     - process_request(request, client_address)
 132     - handle_error()
 133
 134     Methods for derived classes:
 135
 136     - finish_request(request, client_address)
 137
 138     Class variables that may be overridden by derived classes or
 139     instances:
 140
 141     - address_family
 142     - socket_type
 143     - request_queue_size (only for stream sockets)
 144
 145     Instance variables:
 146
 147     - server_address
 148     - RequestHandlerClass
 149     - socket
 150
 151     """
 152
 153     address_family = socket.AF_INET
 154
 155     socket_type = socket.SOCK_STREAM
 156
 157     request_queue_size = 5
 158
 159     def __init__(self, server_address, RequestHandlerClass):
 160         """Constructor.  May be extended, do not override."""
 161         self.server_address = server_address
 162         self.RequestHandlerClass = RequestHandlerClass
 163         self.socket = socket.socket(self.address_family,
 164                                     self.socket_type)
 165         self.server_bind()
 166         self.server_activate()
 167
 168     def server_bind(self):
 169         """Called by constructor to bind the socket.
 170
 171         May be overridden.
 172
 173         """
 174         self.socket.bind(self.server_address)
 175
 176     def server_activate(self):
 177         """Called by constructor to activate the server.
 178
 179         May be overridden.
 180
 181         """
 182         self.socket.listen(self.request_queue_size)
 183
 184     def fileno(self):
 185         """Return socket file number.
 186
 187         Interface required by select().
 188
 189         """
 190         return self.socket.fileno()
 191
 192     def serve_forever(self):
 193         """Handle one request at a time until doomsday."""
 194         while 1:
 195             self.handle_request()
 196
 197     # The distinction between handling, getting, processing and
 198     # finishing a request is fairly arbitrary.  Remember:
 199     #
 200     # - handle_request() is the top-level call.  It calls
 201     #   get_request(), verify_request() and process_request()
 202     # - get_request() is different for stream or datagram sockets
 203     # - process_request() is the place that may fork a new process
 204     #   or create a new thread to finish the request
 205     # - finish_request() instantiates the request handler class;
 206     #   this constructor will handle the request all by itself
 207
 208     def handle_request(self):
 209         """Handle one request, possibly blocking."""
 210         request, client_address = self.get_request()
 211         if self.verify_request(request, client_address):
 212             try:
 213                 self.process_request(request, client_address)
 214             except:
 215                 self.handle_error(request, client_address)
 216
 217     def get_request(self):
 218         """Get the request and client address from the socket.
 219
 220         May be overridden.
 221
 222         """
 223         return self.socket.accept()
 224
 225     def verify_request(self, request, client_address):
 226         """Verify the request.  May be overridden.
 227
 228         Return true if we should proceed with this request.
 229
 230         """
 231         return 1
 232
 233     def process_request(self, request, client_address):
 234         """Call finish_request.
 235
 236         Overridden by ForkingMixIn and ThreadingMixIn.
 237
 238         """
 239         self.finish_request(request, client_address)
 240
 241     def finish_request(self, request, client_address):
 242         """Finish one request by instantiating RequestHandlerClass."""
 243         self.RequestHandlerClass(request, client_address, self)
 244
 245     def handle_error(self, request, client_address):
 246         """Handle an error gracefully.  May be overridden.
 247
 248         The default is to print a traceback and continue.
 249
 250         """
 251         print '-'*40
 252         print 'Exception happened during processing of request from',
 253         print client_address
 254         import traceback
 255         traceback.print_exc()
 256         print '-'*40
 257
 258
 259 class UDPServer(TCPServer):
 260
 261     """UDP server class."""
 262
 263     socket_type = socket.SOCK_DGRAM
 264
 265     max_packet_size = 8192
 266
 267     def get_request(self):
 268         data, client_addr = self.socket.recvfrom(self.max_packet_size)
 269         return (data, self.socket), client_addr
 270
 271     def server_activate(self):
 272         # No need to call listen() for UDP.
 273         pass
 274
 275
 276 class ForkingMixIn:
 277
 278     """Mix-in class to handle each request in a new process."""
 279
 280     active_children = None
 281
 282     def collect_children(self):
 283         """Internal routine to wait for died children."""
 284         while self.active_children:
 285             pid, status = os.waitpid(0, os.WNOHANG)
 286             if not pid: break
 287             self.active_children.remove(pid)
 288
 289     def process_request(self, request, client_address):
 290         """Fork a new subprocess to process the request."""
 291         self.collect_children()
 292         pid = os.fork()
 293         if pid:
 294             # Parent process
 295             if self.active_children is None:
 296                 self.active_children = []
 297             self.active_children.append(pid)
 298             return
 299         else:
 300             # Child process.
 301             # This must never return, hence os._exit()!
 302             try:
 303                 self.finish_request(request, client_address)
 304                 os._exit(0)
 305             except:
 306                 try:
 307                     self.handle_error(request,
 308                                       client_address)
 309                 finally:
 310                     os._exit(1)
 311
 312
 313 class ThreadingMixIn:
 314
 315     """Mix-in class to handle each request in a new thread."""
 316
 317     def process_request(self, request, client_address):
 318         """Start a new thread to process the request."""
 319         import thread
 320         thread.start_new_thread(self.finish_request,
 321                                 (request, client_address))
 322
 323
 324 class ForkingUDPServer(ForkingMixIn, UDPServer): pass
 325 class ForkingTCPServer(ForkingMixIn, TCPServer): pass
 326
 327 class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
 328 class ThreadingTCPServer(ThreadingMixIn, TCPServer): pass
 329
 330 if hasattr(socket, 'AF_UNIX'):
 331
 332     class UnixStreamServer(TCPServer):
 333         address_family = socket.AF_UNIX
 334
 335     class UnixDatagramServer(UDPServer):
 336         address_family = socket.AF_UNIX
 337
 338     class ThreadingUnixStreamServer(ThreadingMixIn, UnixStreamServer): pass
 339
 340     class ThreadingUnixDatagramServer(ThreadingMixIn, UnixDatagramServer): pass
 341
 342 class BaseRequestHandler:
 343
 344     """Base class for request handler classes.
 345
 346     This class is instantiated for each request to be handled.  The
 347     constructor sets the instance variables request, client_address
 348     and server, and then calls the handle() method.  To implement a
 349     specific service, all you need to do is to derive a class which
 350     defines a handle() method.
 351
 352     The handle() method can find the request as self.request, the
 353     client address as self.client_address, and the server (in case it
 354     needs access to per-server information) as self.server.  Since a
 355     separate instance is created for each request, the handle() method
 356     can define arbitrary other instance variariables.
 357
 358     """
 359
 360     def __init__(self, request, client_address, server):
 361         self.request = request
 362         self.client_address = client_address
 363         self.server = server
 364         try:
 365             self.setup()
 366             self.handle()
 367             self.finish()
 368         finally:
 369             sys.exc_traceback = None    # Help garbage collection
 370
 371     def setup(self):
 372         pass
 373
 374     def __del__(self):
 375         pass
 376
 377     def handle(self):
 378         pass
 379
 380     def finish(self):
 381         pass
 382
 383
 384 # The following two classes make it possible to use the same service
 385 # class for stream or datagram servers.
 386 # Each class sets up these instance variables:
 387 # - rfile: a file object from which receives the request is read
 388 # - wfile: a file object to which the reply is written
 389 # When the handle() method returns, wfile is flushed properly
 390
 391
 392 class StreamRequestHandler(BaseRequestHandler):
 393
 394     """Define self.rfile and self.wfile for stream sockets."""
 395
 396     def setup(self):
 397         self.connection = self.request
 398         self.rfile = self.connection.makefile('rb', 0)
 399         self.wfile = self.connection.makefile('wb', 0)
 400
 401     def finish(self):
 402         self.wfile.flush()
 403         self.wfile.close()
 404         self.rfile.close()
 405
 406
 407 class DatagramRequestHandler(BaseRequestHandler):
 408
 409     """Define self.rfile and self.wfile for datagram sockets."""
 410
 411     def setup(self):
 412         import StringIO
 413         self.packet, self.socket = self.request
 414         self.rfile = StringIO.StringIO(self.packet)
 415         self.wfile = StringIO.StringIO(self.packet)
 416
 417     def finish(self):
 418         self.socket.sendto(self.wfile.getvalue(), self.client_address)