blob: e9e4e4e4add0cdcbcea4bbd75409d833573646dd [file] [log] [blame]
Guido van Rossume7e578f1995-08-04 04:00:20 +00001"""Generic socket server classes.
2
3This module tries to capture the various aspects of defining a server:
4
Guido van Rossum90cb9062001-01-19 00:44:41 +00005For socket-based servers:
6
Guido van Rossume7e578f1995-08-04 04:00:20 +00007- address family:
Martin v. Löwisa43c2f82001-07-24 20:34:08 +00008 - AF_INET{,6}: IP (Internet Protocol) sockets (default)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +00009 - AF_UNIX: Unix domain sockets
10 - others, e.g. AF_DECNET are conceivable (see <socket.h>
Guido van Rossume7e578f1995-08-04 04:00:20 +000011- socket type:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000012 - SOCK_STREAM (reliable stream, e.g. TCP)
13 - SOCK_DGRAM (datagrams, e.g. UDP)
Guido van Rossum90cb9062001-01-19 00:44:41 +000014
15For request-based servers (including socket-based):
16
Guido van Rossume7e578f1995-08-04 04:00:20 +000017- client address verification before further looking at the request
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000018 (This is actually a hook for any processing that needs to look
19 at the request before anything else, e.g. logging)
Guido van Rossume7e578f1995-08-04 04:00:20 +000020- how to handle multiple requests:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000021 - synchronous (one request is handled at a time)
22 - forking (each request is handled by a new process)
23 - threading (each request is handled by a new thread)
Guido van Rossume7e578f1995-08-04 04:00:20 +000024
25The classes in this module favor the server type that is simplest to
26write: a synchronous TCP/IP server. This is bad class design, but
27save some typing. (There's also the issue that a deep class hierarchy
28slows down method lookups.)
29
Guido van Rossum90cb9062001-01-19 00:44:41 +000030There are five classes in an inheritance diagram, four of which represent
Guido van Rossume7e578f1995-08-04 04:00:20 +000031synchronous servers of four types:
32
Guido van Rossum90cb9062001-01-19 00:44:41 +000033 +------------+
34 | BaseServer |
35 +------------+
36 |
37 v
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000038 +-----------+ +------------------+
39 | TCPServer |------->| UnixStreamServer |
40 +-----------+ +------------------+
41 |
42 v
43 +-----------+ +--------------------+
44 | UDPServer |------->| UnixDatagramServer |
45 +-----------+ +--------------------+
Guido van Rossume7e578f1995-08-04 04:00:20 +000046
Guido van Rossumdb2b70c1997-07-16 16:21:38 +000047Note that UnixDatagramServer derives from UDPServer, not from
Guido van Rossume7e578f1995-08-04 04:00:20 +000048UnixStreamServer -- the only difference between an IP and a Unix
49stream server is the address family, which is simply repeated in both
Guido van Rossumdb2b70c1997-07-16 16:21:38 +000050unix server classes.
Guido van Rossume7e578f1995-08-04 04:00:20 +000051
52Forking and threading versions of each type of server can be created
Guido van Rossumebbffd42005-04-30 00:20:35 +000053using the ForkingMixIn and ThreadingMixIn mix-in classes. For
Guido van Rossume7e578f1995-08-04 04:00:20 +000054instance, a threading UDP server class is created as follows:
55
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000056 class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
Guido van Rossume7e578f1995-08-04 04:00:20 +000057
Guido van Rossumdb2b70c1997-07-16 16:21:38 +000058The Mix-in class must come first, since it overrides a method defined
Martin v. Löwisf86e8ef2002-11-22 08:08:44 +000059in UDPServer! Setting the various member variables also changes
60the behavior of the underlying server mechanism.
Guido van Rossume7e578f1995-08-04 04:00:20 +000061
62To implement a service, you must derive a class from
63BaseRequestHandler and redefine its handle() method. You can then run
64various versions of the service by combining one of the server classes
65with your request handler class.
66
67The request handler class must be different for datagram or stream
Georg Brandlca5feab2005-07-18 07:38:44 +000068services. This can be hidden by using the request handler
69subclasses StreamRequestHandler or DatagramRequestHandler.
Guido van Rossume7e578f1995-08-04 04:00:20 +000070
71Of course, you still have to use your head!
72
73For instance, it makes no sense to use a forking server if the service
74contains state in memory that can be modified by requests (since the
75modifications in the child process would never reach the initial state
76kept in the parent process and passed to each child). In this case,
77you can use a threading server, but you will probably have to use
78locks to avoid two requests that come in nearly simultaneous to apply
79conflicting changes to the server state.
80
81On the other hand, if you are building e.g. an HTTP server, where all
82data is stored externally (e.g. in the file system), a synchronous
83class will essentially render the service "deaf" while one request is
84being handled -- which may be for a very long time if a client is slow
Ezio Melottif78869e2011-10-29 10:41:51 +030085to read all the data it has requested. Here a threading or forking
Guido van Rossume7e578f1995-08-04 04:00:20 +000086server is appropriate.
87
88In some cases, it may be appropriate to process part of a request
89synchronously, but to finish processing in a forked child depending on
90the request data. This can be implemented by using a synchronous
Guido van Rossum90cb9062001-01-19 00:44:41 +000091server and doing an explicit fork in the request handler class
Guido van Rossume7e578f1995-08-04 04:00:20 +000092handle() method.
93
94Another approach to handling multiple simultaneous requests in an
95environment that supports neither threads nor fork (or where these are
96too expensive or inappropriate for the service) is to maintain an
97explicit table of partially finished requests and to use select() to
98decide which request to work on next (or whether to handle a new
99incoming request). This is particularly important for stream services
100where each client can potentially be connected for a long time (if
Guido van Rossum90cb9062001-01-19 00:44:41 +0000101threads or subprocesses cannot be used).
Guido van Rossume7e578f1995-08-04 04:00:20 +0000102
103Future work:
104- Standard classes for Sun RPC (which uses either UDP or TCP)
105- Standard mix-in classes to implement various authentication
106 and encryption schemes
107- Standard framework for select-based multiplexing
108
109XXX Open problems:
110- What to do with out-of-band data?
111
Guido van Rossum90cb9062001-01-19 00:44:41 +0000112BaseServer:
113- split generic "request" functionality out into BaseServer class.
114 Copyright (C) 2000 Luke Kenneth Casson Leighton <lkcl@samba.org>
115
116 example: read entries from a SQL database (requires overriding
117 get_request() to return a table entry from the database).
118 entry is processed by a RequestHandlerClass.
119
Guido van Rossume7e578f1995-08-04 04:00:20 +0000120"""
121
Guido van Rossum10b04182001-01-19 16:45:46 +0000122# Author of the BaseServer patch: Luke Kenneth Casson Leighton
Guido van Rossume7e578f1995-08-04 04:00:20 +0000123
Guido van Rossum7de4d642001-07-10 11:50:09 +0000124# XXX Warning!
125# There is a test suite for this module, but it cannot be run by the
126# standard regression test.
127# To run it manually, run Lib/test/test_socketserver.py.
128
129__version__ = "0.4"
Guido van Rossume7e578f1995-08-04 04:00:20 +0000130
131
132import socket
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000133import select
Guido van Rossume7e578f1995-08-04 04:00:20 +0000134import sys
135import os
Antoine Pitroub0a9c662012-04-09 00:47:24 +0200136import errno
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000137try:
138 import threading
Brett Cannoncd171c82013-07-04 17:43:24 -0400139except ImportError:
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000140 import dummy_threading as threading
Guido van Rossume7e578f1995-08-04 04:00:20 +0000141
Skip Montanaroe99d5ea2001-01-20 19:54:20 +0000142__all__ = ["TCPServer","UDPServer","ForkingUDPServer","ForkingTCPServer",
143 "ThreadingUDPServer","ThreadingTCPServer","BaseRequestHandler",
Guido van Rossum7de4d642001-07-10 11:50:09 +0000144 "StreamRequestHandler","DatagramRequestHandler",
145 "ThreadingMixIn", "ForkingMixIn"]
Skip Montanaroe99d5ea2001-01-20 19:54:20 +0000146if hasattr(socket, "AF_UNIX"):
147 __all__.extend(["UnixStreamServer","UnixDatagramServer",
148 "ThreadingUnixStreamServer",
149 "ThreadingUnixDatagramServer"])
Guido van Rossume7e578f1995-08-04 04:00:20 +0000150
Antoine Pitroub0a9c662012-04-09 00:47:24 +0200151def _eintr_retry(func, *args):
152 """restart a system call interrupted by EINTR"""
153 while True:
154 try:
155 return func(*args)
156 except OSError as e:
157 if e.errno != errno.EINTR:
158 raise
159
Guido van Rossum90cb9062001-01-19 00:44:41 +0000160class BaseServer:
161
162 """Base class for server classes.
163
164 Methods for the caller:
165
166 - __init__(server_address, RequestHandlerClass)
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000167 - serve_forever(poll_interval=0.5)
168 - shutdown()
Guido van Rossum90cb9062001-01-19 00:44:41 +0000169 - handle_request() # if you do not use serve_forever()
170 - fileno() -> int # for select()
171
172 Methods that may be overridden:
173
174 - server_bind()
175 - server_activate()
176 - get_request() -> request, client_address
Georg Brandlfceab5a2008-01-19 20:08:23 +0000177 - handle_timeout()
Guido van Rossum90cb9062001-01-19 00:44:41 +0000178 - verify_request(request, client_address)
179 - server_close()
180 - process_request(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000181 - shutdown_request(request)
Ka-Ping Yee285a7e52001-04-11 04:02:05 +0000182 - close_request(request)
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800183 - service_actions()
Guido van Rossum90cb9062001-01-19 00:44:41 +0000184 - handle_error()
185
186 Methods for derived classes:
187
188 - finish_request(request, client_address)
189
190 Class variables that may be overridden by derived classes or
191 instances:
192
Georg Brandlfceab5a2008-01-19 20:08:23 +0000193 - timeout
Guido van Rossum90cb9062001-01-19 00:44:41 +0000194 - address_family
195 - socket_type
Barry Warsawb97f0b72003-10-09 23:48:52 +0000196 - allow_reuse_address
Guido van Rossum90cb9062001-01-19 00:44:41 +0000197
198 Instance variables:
199
200 - RequestHandlerClass
201 - socket
202
203 """
204
Georg Brandlfceab5a2008-01-19 20:08:23 +0000205 timeout = None
206
Guido van Rossum90cb9062001-01-19 00:44:41 +0000207 def __init__(self, server_address, RequestHandlerClass):
208 """Constructor. May be extended, do not override."""
209 self.server_address = server_address
210 self.RequestHandlerClass = RequestHandlerClass
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000211 self.__is_shut_down = threading.Event()
Antoine Pitrou3bcba8e2010-04-25 22:01:43 +0000212 self.__shutdown_request = False
Guido van Rossum90cb9062001-01-19 00:44:41 +0000213
214 def server_activate(self):
215 """Called by constructor to activate the server.
216
217 May be overridden.
218
219 """
220 pass
221
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000222 def serve_forever(self, poll_interval=0.5):
223 """Handle one request at a time until shutdown.
224
225 Polls for shutdown every poll_interval seconds. Ignores
226 self.timeout. If you need to do periodic tasks, do them in
227 another thread.
228 """
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000229 self.__is_shut_down.clear()
Antoine Pitrou3bcba8e2010-04-25 22:01:43 +0000230 try:
231 while not self.__shutdown_request:
232 # XXX: Consider using another file descriptor or
233 # connecting to the socket to wake this up instead of
234 # polling. Polling reduces our responsiveness to a
235 # shutdown request and wastes cpu at all other times.
Antoine Pitroub0a9c662012-04-09 00:47:24 +0200236 r, w, e = _eintr_retry(select.select, [self], [], [],
237 poll_interval)
Antoine Pitrou3bcba8e2010-04-25 22:01:43 +0000238 if self in r:
239 self._handle_request_noblock()
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800240
241 self.service_actions()
Antoine Pitrou3bcba8e2010-04-25 22:01:43 +0000242 finally:
243 self.__shutdown_request = False
244 self.__is_shut_down.set()
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000245
246 def shutdown(self):
247 """Stops the serve_forever loop.
248
249 Blocks until the loop has finished. This must be called while
250 serve_forever() is running in another thread, or it will
251 deadlock.
252 """
Antoine Pitrou3bcba8e2010-04-25 22:01:43 +0000253 self.__shutdown_request = True
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000254 self.__is_shut_down.wait()
Guido van Rossum90cb9062001-01-19 00:44:41 +0000255
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800256 def service_actions(self):
257 """Called by the serve_forever() loop.
258
259 May be overridden by a subclass / Mixin to implement any code that
260 needs to be run during the loop.
261 """
262 pass
263
Guido van Rossum90cb9062001-01-19 00:44:41 +0000264 # The distinction between handling, getting, processing and
265 # finishing a request is fairly arbitrary. Remember:
266 #
267 # - handle_request() is the top-level call. It calls
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000268 # select, get_request(), verify_request() and process_request()
269 # - get_request() is different for stream or datagram sockets
Guido van Rossum90cb9062001-01-19 00:44:41 +0000270 # - process_request() is the place that may fork a new process
271 # or create a new thread to finish the request
272 # - finish_request() instantiates the request handler class;
273 # this constructor will handle the request all by itself
274
275 def handle_request(self):
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000276 """Handle one request, possibly blocking.
277
278 Respects self.timeout.
279 """
280 # Support people who used socket.settimeout() to escape
281 # handle_request before self.timeout was available.
282 timeout = self.socket.gettimeout()
283 if timeout is None:
284 timeout = self.timeout
285 elif self.timeout is not None:
286 timeout = min(timeout, self.timeout)
Antoine Pitroub0a9c662012-04-09 00:47:24 +0200287 fd_sets = _eintr_retry(select.select, [self], [], [], timeout)
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000288 if not fd_sets[0]:
289 self.handle_timeout()
290 return
291 self._handle_request_noblock()
292
293 def _handle_request_noblock(self):
294 """Handle one request, without blocking.
295
296 I assume that select.select has returned that the socket is
297 readable before this function was called, so there should be
298 no risk of blocking in get_request().
299 """
Guido van Rossum90cb9062001-01-19 00:44:41 +0000300 try:
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000301 request, client_address = self.get_request()
Andrew Svetlov0832af62012-12-18 23:10:48 +0200302 except OSError:
Guido van Rossum90cb9062001-01-19 00:44:41 +0000303 return
304 if self.verify_request(request, client_address):
305 try:
306 self.process_request(request, client_address)
307 except:
308 self.handle_error(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000309 self.shutdown_request(request)
Guido van Rossum90cb9062001-01-19 00:44:41 +0000310
Georg Brandlfceab5a2008-01-19 20:08:23 +0000311 def handle_timeout(self):
312 """Called if no new request arrives within self.timeout.
313
314 Overridden by ForkingMixIn.
315 """
316 pass
317
Guido van Rossum90cb9062001-01-19 00:44:41 +0000318 def verify_request(self, request, client_address):
319 """Verify the request. May be overridden.
320
Tim Petersbc0e9102002-04-04 22:55:58 +0000321 Return True if we should proceed with this request.
Guido van Rossum90cb9062001-01-19 00:44:41 +0000322
323 """
Tim Petersbc0e9102002-04-04 22:55:58 +0000324 return True
Guido van Rossum90cb9062001-01-19 00:44:41 +0000325
326 def process_request(self, request, client_address):
327 """Call finish_request.
328
329 Overridden by ForkingMixIn and ThreadingMixIn.
330
331 """
332 self.finish_request(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000333 self.shutdown_request(request)
Guido van Rossum90cb9062001-01-19 00:44:41 +0000334
335 def server_close(self):
336 """Called to clean-up the server.
337
338 May be overridden.
339
340 """
341 pass
342
343 def finish_request(self, request, client_address):
344 """Finish one request by instantiating RequestHandlerClass."""
345 self.RequestHandlerClass(request, client_address, self)
346
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000347 def shutdown_request(self, request):
348 """Called to shutdown and close an individual request."""
349 self.close_request(request)
350
Ka-Ping Yee285a7e52001-04-11 04:02:05 +0000351 def close_request(self, request):
352 """Called to clean up an individual request."""
353 pass
354
Guido van Rossum90cb9062001-01-19 00:44:41 +0000355 def handle_error(self, request, client_address):
356 """Handle an error gracefully. May be overridden.
357
358 The default is to print a traceback and continue.
359
360 """
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000361 print('-'*40)
362 print('Exception happened during processing of request from', end=' ')
363 print(client_address)
Guido van Rossum90cb9062001-01-19 00:44:41 +0000364 import traceback
365 traceback.print_exc() # XXX But this goes to stderr!
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000366 print('-'*40)
Guido van Rossum90cb9062001-01-19 00:44:41 +0000367
368
369class TCPServer(BaseServer):
Guido van Rossume7e578f1995-08-04 04:00:20 +0000370
371 """Base class for various socket-based server classes.
372
373 Defaults to synchronous IP stream (i.e., TCP).
374
375 Methods for the caller:
376
Guido van Rossumd8faa362007-04-27 19:54:29 +0000377 - __init__(server_address, RequestHandlerClass, bind_and_activate=True)
Christian Heimesdd15f6c2008-03-16 00:07:10 +0000378 - serve_forever(poll_interval=0.5)
379 - shutdown()
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000380 - handle_request() # if you don't use serve_forever()
381 - fileno() -> int # for select()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000382
383 Methods that may be overridden:
384
385 - server_bind()
386 - server_activate()
387 - get_request() -> request, client_address
Georg Brandlfceab5a2008-01-19 20:08:23 +0000388 - handle_timeout()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000389 - verify_request(request, client_address)
390 - process_request(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000391 - shutdown_request(request)
Ka-Ping Yee285a7e52001-04-11 04:02:05 +0000392 - close_request(request)
Guido van Rossume7e578f1995-08-04 04:00:20 +0000393 - handle_error()
394
395 Methods for derived classes:
396
397 - finish_request(request, client_address)
398
399 Class variables that may be overridden by derived classes or
400 instances:
401
Georg Brandlfceab5a2008-01-19 20:08:23 +0000402 - timeout
Guido van Rossume7e578f1995-08-04 04:00:20 +0000403 - address_family
404 - socket_type
405 - request_queue_size (only for stream sockets)
Barry Warsaw3aaad502003-10-09 22:44:05 +0000406 - allow_reuse_address
Guido van Rossume7e578f1995-08-04 04:00:20 +0000407
408 Instance variables:
409
410 - server_address
411 - RequestHandlerClass
412 - socket
413
414 """
415
416 address_family = socket.AF_INET
417
418 socket_type = socket.SOCK_STREAM
419
420 request_queue_size = 5
421
Raymond Hettingerc8f80342002-08-25 16:36:49 +0000422 allow_reuse_address = False
Guido van Rossume3c7a5f2000-05-09 14:53:29 +0000423
Guido van Rossumd8faa362007-04-27 19:54:29 +0000424 def __init__(self, server_address, RequestHandlerClass, bind_and_activate=True):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000425 """Constructor. May be extended, do not override."""
Guido van Rossum90cb9062001-01-19 00:44:41 +0000426 BaseServer.__init__(self, server_address, RequestHandlerClass)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000427 self.socket = socket.socket(self.address_family,
428 self.socket_type)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000429 if bind_and_activate:
430 self.server_bind()
431 self.server_activate()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000432
433 def server_bind(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000434 """Called by constructor to bind the socket.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000435
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000436 May be overridden.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000437
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000438 """
Guido van Rossume3c7a5f2000-05-09 14:53:29 +0000439 if self.allow_reuse_address:
440 self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000441 self.socket.bind(self.server_address)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000442 self.server_address = self.socket.getsockname()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000443
444 def server_activate(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000445 """Called by constructor to activate the server.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000446
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000447 May be overridden.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000448
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000449 """
450 self.socket.listen(self.request_queue_size)
Guido van Rossume7e578f1995-08-04 04:00:20 +0000451
Guido van Rossum90cb9062001-01-19 00:44:41 +0000452 def server_close(self):
453 """Called to clean-up the server.
454
455 May be overridden.
456
457 """
458 self.socket.close()
459
Guido van Rossume7e578f1995-08-04 04:00:20 +0000460 def fileno(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000461 """Return socket file number.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000462
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000463 Interface required by select().
Guido van Rossume7e578f1995-08-04 04:00:20 +0000464
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000465 """
466 return self.socket.fileno()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000467
Guido van Rossume7e578f1995-08-04 04:00:20 +0000468 def get_request(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000469 """Get the request and client address from the socket.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000470
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000471 May be overridden.
Guido van Rossume7e578f1995-08-04 04:00:20 +0000472
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000473 """
474 return self.socket.accept()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000475
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000476 def shutdown_request(self, request):
477 """Called to shutdown and close an individual request."""
Kristján Valur Jónsson200cfd02009-07-04 15:18:00 +0000478 try:
479 #explicitly shutdown. socket.close() merely releases
480 #the socket and waits for GC to perform the actual close.
481 request.shutdown(socket.SHUT_WR)
Andrew Svetlov0832af62012-12-18 23:10:48 +0200482 except OSError:
Kristján Valur Jónsson200cfd02009-07-04 15:18:00 +0000483 pass #some platforms may raise ENOTCONN here
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000484 self.close_request(request)
485
486 def close_request(self, request):
487 """Called to clean up an individual request."""
Ka-Ping Yee285a7e52001-04-11 04:02:05 +0000488 request.close()
489
Guido van Rossume7e578f1995-08-04 04:00:20 +0000490
491class UDPServer(TCPServer):
492
493 """UDP server class."""
494
Raymond Hettingerc8f80342002-08-25 16:36:49 +0000495 allow_reuse_address = False
Guido van Rossum90cb9062001-01-19 00:44:41 +0000496
Guido van Rossume7e578f1995-08-04 04:00:20 +0000497 socket_type = socket.SOCK_DGRAM
498
499 max_packet_size = 8192
500
501 def get_request(self):
Guido van Rossum32490821998-06-16 02:27:33 +0000502 data, client_addr = self.socket.recvfrom(self.max_packet_size)
503 return (data, self.socket), client_addr
504
505 def server_activate(self):
506 # No need to call listen() for UDP.
507 pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000508
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000509 def shutdown_request(self, request):
510 # No need to shutdown anything.
511 self.close_request(request)
512
Ka-Ping Yee285a7e52001-04-11 04:02:05 +0000513 def close_request(self, request):
514 # No need to close anything.
515 pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000516
Guido van Rossume7e578f1995-08-04 04:00:20 +0000517class ForkingMixIn:
518
519 """Mix-in class to handle each request in a new process."""
520
Georg Brandlfceab5a2008-01-19 20:08:23 +0000521 timeout = 300
Guido van Rossume7e578f1995-08-04 04:00:20 +0000522 active_children = None
Guido van Rossum2ab455a1999-07-28 21:39:28 +0000523 max_children = 40
Guido van Rossume7e578f1995-08-04 04:00:20 +0000524
525 def collect_children(self):
Georg Brandlfceab5a2008-01-19 20:08:23 +0000526 """Internal routine to wait for children that have exited."""
Christian Heimes70e7ea22008-02-28 20:02:27 +0000527 if self.active_children is None: return
528 while len(self.active_children) >= self.max_children:
529 # XXX: This will wait for any child process, not just ones
530 # spawned by this library. This could confuse other
531 # libraries that expect to be able to wait for their own
532 # children.
Guido van Rossumbfadac01999-06-17 15:41:33 +0000533 try:
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000534 pid, status = os.waitpid(0, 0)
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200535 except OSError:
Guido van Rossumbfadac01999-06-17 15:41:33 +0000536 pid = None
Christian Heimes70e7ea22008-02-28 20:02:27 +0000537 if pid not in self.active_children: continue
538 self.active_children.remove(pid)
539
540 # XXX: This loop runs more system calls than it ought
541 # to. There should be a way to put the active_children into a
542 # process group and then use os.waitpid(-pgid) to wait for any
543 # of that set, but I couldn't find a way to allocate pgids
544 # that couldn't collide.
545 for child in self.active_children:
546 try:
547 pid, status = os.waitpid(child, os.WNOHANG)
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200548 except OSError:
Christian Heimes70e7ea22008-02-28 20:02:27 +0000549 pid = None
550 if not pid: continue
Christian Heimesa156e092008-02-16 07:38:31 +0000551 try:
552 self.active_children.remove(pid)
553 except ValueError as e:
554 raise ValueError('%s. x=%d and list=%r' % (e.message, pid,
555 self.active_children))
Guido van Rossume7e578f1995-08-04 04:00:20 +0000556
Georg Brandlfceab5a2008-01-19 20:08:23 +0000557 def handle_timeout(self):
558 """Wait for zombies after self.timeout seconds of inactivity.
559
560 May be extended, do not override.
561 """
562 self.collect_children()
563
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800564 def service_actions(self):
R David Murray258fabe2012-10-01 21:43:46 -0400565 """Collect the zombie child processes regularly in the ForkingMixIn.
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800566
567 service_actions is called in the BaseServer's serve_forver loop.
568 """
569 self.collect_children()
570
Guido van Rossume7e578f1995-08-04 04:00:20 +0000571 def process_request(self, request, client_address):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000572 """Fork a new subprocess to process the request."""
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000573 pid = os.fork()
574 if pid:
575 # Parent process
576 if self.active_children is None:
577 self.active_children = []
578 self.active_children.append(pid)
Guido van Rossum7de4d642001-07-10 11:50:09 +0000579 self.close_request(request)
Senthil Kumaran5e826e82011-05-26 00:22:59 +0800580 return
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000581 else:
582 # Child process.
583 # This must never return, hence os._exit()!
584 try:
585 self.finish_request(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000586 self.shutdown_request(request)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000587 os._exit(0)
588 except:
589 try:
Guido van Rossum7de4d642001-07-10 11:50:09 +0000590 self.handle_error(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000591 self.shutdown_request(request)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000592 finally:
593 os._exit(1)
Guido van Rossume7e578f1995-08-04 04:00:20 +0000594
595
596class ThreadingMixIn:
Guido van Rossume7e578f1995-08-04 04:00:20 +0000597 """Mix-in class to handle each request in a new thread."""
598
Martin v. Löwisf86e8ef2002-11-22 08:08:44 +0000599 # Decides how threads will act upon termination of the
600 # main process
Fred Drake132e0e82002-11-22 14:22:49 +0000601 daemon_threads = False
Martin v. Löwisf86e8ef2002-11-22 08:08:44 +0000602
Guido van Rossuma5343cc2001-10-18 18:02:07 +0000603 def process_request_thread(self, request, client_address):
Guido van Rossum83c32812001-10-23 21:42:45 +0000604 """Same as in BaseServer but as a thread.
605
606 In addition, exception handling is done here.
607
608 """
609 try:
610 self.finish_request(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000611 self.shutdown_request(request)
Guido van Rossum83c32812001-10-23 21:42:45 +0000612 except:
613 self.handle_error(request, client_address)
Kristján Valur Jónssona5b47ce2009-07-07 09:09:10 +0000614 self.shutdown_request(request)
Guido van Rossuma5343cc2001-10-18 18:02:07 +0000615
Guido van Rossume7e578f1995-08-04 04:00:20 +0000616 def process_request(self, request, client_address):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000617 """Start a new thread to process the request."""
Guido van Rossuma5343cc2001-10-18 18:02:07 +0000618 t = threading.Thread(target = self.process_request_thread,
Jeremy Hylton75260271999-10-12 16:20:13 +0000619 args = (request, client_address))
Florent Xicluna12b66b52011-11-04 10:16:28 +0100620 t.daemon = self.daemon_threads
Jeremy Hylton75260271999-10-12 16:20:13 +0000621 t.start()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000622
623
624class ForkingUDPServer(ForkingMixIn, UDPServer): pass
625class ForkingTCPServer(ForkingMixIn, TCPServer): pass
626
627class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
628class ThreadingTCPServer(ThreadingMixIn, TCPServer): pass
629
Guido van Rossum67a40e81998-11-30 15:07:01 +0000630if hasattr(socket, 'AF_UNIX'):
631
632 class UnixStreamServer(TCPServer):
633 address_family = socket.AF_UNIX
634
635 class UnixDatagramServer(UDPServer):
636 address_family = socket.AF_UNIX
637
638 class ThreadingUnixStreamServer(ThreadingMixIn, UnixStreamServer): pass
639
640 class ThreadingUnixDatagramServer(ThreadingMixIn, UnixDatagramServer): pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000641
642class BaseRequestHandler:
643
644 """Base class for request handler classes.
645
646 This class is instantiated for each request to be handled. The
647 constructor sets the instance variables request, client_address
648 and server, and then calls the handle() method. To implement a
649 specific service, all you need to do is to derive a class which
650 defines a handle() method.
651
652 The handle() method can find the request as self.request, the
Guido van Rossumfdb3d1a1998-11-16 19:06:30 +0000653 client address as self.client_address, and the server (in case it
Guido van Rossume7e578f1995-08-04 04:00:20 +0000654 needs access to per-server information) as self.server. Since a
655 separate instance is created for each request, the handle() method
656 can define arbitrary other instance variariables.
657
658 """
659
660 def __init__(self, request, client_address, server):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000661 self.request = request
662 self.client_address = client_address
663 self.server = server
Guido van Rossume7ba4952007-06-06 23:52:48 +0000664 self.setup()
Kristján Valur Jónsson985fc6a2009-07-01 10:01:31 +0000665 try:
666 self.handle()
667 finally:
668 self.finish()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000669
670 def setup(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000671 pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000672
Guido van Rossume7e578f1995-08-04 04:00:20 +0000673 def handle(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000674 pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000675
676 def finish(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000677 pass
Guido van Rossume7e578f1995-08-04 04:00:20 +0000678
679
680# The following two classes make it possible to use the same service
681# class for stream or datagram servers.
682# Each class sets up these instance variables:
683# - rfile: a file object from which receives the request is read
684# - wfile: a file object to which the reply is written
685# When the handle() method returns, wfile is flushed properly
686
687
688class StreamRequestHandler(BaseRequestHandler):
689
690 """Define self.rfile and self.wfile for stream sockets."""
691
Guido van Rossum01fed4d2000-09-01 03:25:14 +0000692 # Default buffer sizes for rfile, wfile.
693 # We default rfile to buffered because otherwise it could be
694 # really slow for large data (a getc() call per byte); we make
695 # wfile unbuffered because (a) often after a write() we want to
696 # read and we need to flush the line; (b) big writes to unbuffered
697 # files are typically optimized by stdio even when big reads
698 # aren't.
699 rbufsize = -1
700 wbufsize = 0
701
Kristján Valur Jónsson985fc6a2009-07-01 10:01:31 +0000702 # A timeout to apply to the request socket, if not None.
703 timeout = None
704
Ezio Melotti4969f702011-03-15 05:59:46 +0200705 # Disable nagle algorithm for this socket, if True.
Kristján Valur Jónsson41a57502009-06-28 21:34:22 +0000706 # Use only when wbufsize != 0, to avoid small packets.
707 disable_nagle_algorithm = False
708
Guido van Rossume7e578f1995-08-04 04:00:20 +0000709 def setup(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000710 self.connection = self.request
Kristján Valur Jónsson985fc6a2009-07-01 10:01:31 +0000711 if self.timeout is not None:
712 self.connection.settimeout(self.timeout)
Kristján Valur Jónsson41a57502009-06-28 21:34:22 +0000713 if self.disable_nagle_algorithm:
714 self.connection.setsockopt(socket.IPPROTO_TCP,
715 socket.TCP_NODELAY, True)
Guido van Rossum01fed4d2000-09-01 03:25:14 +0000716 self.rfile = self.connection.makefile('rb', self.rbufsize)
717 self.wfile = self.connection.makefile('wb', self.wbufsize)
Guido van Rossume7e578f1995-08-04 04:00:20 +0000718
719 def finish(self):
Anthony Baxter4cedc1e2003-01-02 03:07:48 +0000720 if not self.wfile.closed:
Kristján Valur Jónsson36852b72012-12-25 22:46:32 +0000721 try:
722 self.wfile.flush()
723 except socket.error:
724 # An final socket error may have occurred here, such as
725 # the local error ECONNABORTED.
726 pass
Guido van Rossum1d5102c1998-04-03 16:49:52 +0000727 self.wfile.close()
728 self.rfile.close()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000729
730
731class DatagramRequestHandler(BaseRequestHandler):
732
Guido van Rossum7de4d642001-07-10 11:50:09 +0000733 # XXX Regrettably, I cannot get this working on Linux;
734 # s.recvfrom() doesn't return a meaningful client address.
735
Guido van Rossume7e578f1995-08-04 04:00:20 +0000736 """Define self.rfile and self.wfile for datagram sockets."""
737
738 def setup(self):
Guido van Rossum15863ea2007-08-03 19:03:39 +0000739 from io import BytesIO
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000740 self.packet, self.socket = self.request
Guido van Rossum15863ea2007-08-03 19:03:39 +0000741 self.rfile = BytesIO(self.packet)
742 self.wfile = BytesIO()
Guido van Rossume7e578f1995-08-04 04:00:20 +0000743
744 def finish(self):
Guido van Rossum32490821998-06-16 02:27:33 +0000745 self.socket.sendto(self.wfile.getvalue(), self.client_address)