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