blob: 1e51cd6a1d354dbd15838a56d8bb2d9181b97f57 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{SocketServer} ---
Fred Drakef8ca7d82000-10-10 17:03:45 +00002 A framework for network servers}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakef8ca7d82000-10-10 17:03:45 +00004\declaremodule{standard}{SocketServer}
Fred Drakeb91e9341998-07-23 17:59:49 +00005\modulesynopsis{A framework for network servers.}
6
Guido van Rossum6181e001997-05-19 19:55:16 +00007
Fred Drakebe2b6d71998-03-14 06:40:34 +00008The \module{SocketServer} module simplifies the task of writing network
Fred Drake0d3b4f81997-12-04 14:36:52 +00009servers.
Guido van Rossum6181e001997-05-19 19:55:16 +000010
Fred Drakebe2b6d71998-03-14 06:40:34 +000011There are four basic server classes: \class{TCPServer} uses the
Guido van Rossum6181e001997-05-19 19:55:16 +000012Internet TCP protocol, which provides for continuous streams of data
Fred Drakebe2b6d71998-03-14 06:40:34 +000013between the client and server. \class{UDPServer} uses datagrams, which
Guido van Rossum6181e001997-05-19 19:55:16 +000014are discrete packets of information that may arrive out of order or be
15lost while in transit. The more infrequently used
Fred Drakebe2b6d71998-03-14 06:40:34 +000016\class{UnixStreamServer} and \class{UnixDatagramServer} classes are
Fred Drakea8090641998-01-13 19:10:02 +000017similar, but use \UNIX{} domain sockets; they're not available on
18non-\UNIX{} platforms. For more details on network programming, consult
Fred Drake37f15741999-11-10 16:21:37 +000019a book such as W. Richard Steven's \citetitle{UNIX Network Programming}
20or Ralph Davis's \citetitle{Win32 Network Programming}.
Guido van Rossum6181e001997-05-19 19:55:16 +000021
22These four classes process requests \dfn{synchronously}; each request
23must be completed before the next request can be started. This isn't
24suitable if each request takes a long time to complete, because it
25requires a lot of computation, or because it returns a lot of data
26which the client is slow to process. The solution is to create a
27separate process or thread to handle each request; the
Fred Drakebe2b6d71998-03-14 06:40:34 +000028\class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be
Guido van Rossum6181e001997-05-19 19:55:16 +000029used to support asynchronous behaviour.
30
31Creating a server requires several steps. First, you must create a
Fred Drakebe2b6d71998-03-14 06:40:34 +000032request handler class by subclassing the \class{BaseRequestHandler}
33class and overriding its \method{handle()} method; this method will
Guido van Rossum6181e001997-05-19 19:55:16 +000034process incoming requests. Second, you must instantiate one of the
35server classes, passing it the server's address and the request
Fred Drakebe2b6d71998-03-14 06:40:34 +000036handler class. Finally, call the \method{handle_request()} or
37\method{serve_forever()} method of the server object to process one or
Guido van Rossum6181e001997-05-19 19:55:16 +000038many requests.
39
40Server classes have the same external methods and attributes, no
41matter what network protocol they use:
42
Fred Drake19479911998-02-13 06:58:54 +000043\setindexsubitem{(SocketServer protocol)}
Fred Drake798654f1997-11-30 05:53:22 +000044
Guido van Rossum6181e001997-05-19 19:55:16 +000045%XXX should data and methods be intermingled, or separate?
46% how should the distinction between class and instance variables be
47% drawn?
48
49\begin{funcdesc}{fileno}{}
50Return an integer file descriptor for the socket on which the server
51is listening. This function is most commonly passed to
Fred Drakebe2b6d71998-03-14 06:40:34 +000052\function{select.select()}, to allow monitoring multiple servers in the
Guido van Rossum6181e001997-05-19 19:55:16 +000053same process.
54\end{funcdesc}
55
56\begin{funcdesc}{handle_request}{}
57Process a single request. This function calls the following methods
Fred Drakebe2b6d71998-03-14 06:40:34 +000058in order: \method{get_request()}, \method{verify_request()}, and
59\method{process_request()}. If the user-provided \method{handle()}
60method of the handler class raises an exception, the server's
61\method{handle_error()} method will be called.
Guido van Rossum6181e001997-05-19 19:55:16 +000062\end{funcdesc}
63
64\begin{funcdesc}{serve_forever}{}
65Handle an infinite number of requests. This simply calls
Fred Drakebe2b6d71998-03-14 06:40:34 +000066\method{handle_request()} inside an infinite loop.
Guido van Rossum6181e001997-05-19 19:55:16 +000067\end{funcdesc}
68
69\begin{datadesc}{address_family}
70The family of protocols to which the server's socket belongs.
Fred Drakebe2b6d71998-03-14 06:40:34 +000071\constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two
72possible values.
Guido van Rossum6181e001997-05-19 19:55:16 +000073\end{datadesc}
74
75\begin{datadesc}{RequestHandlerClass}
76The user-provided request handler class; an instance of this class is
77created for each request.
78\end{datadesc}
79
80\begin{datadesc}{server_address}
81The address on which the server is listening. The format of addresses
82varies depending on the protocol family; see the documentation for the
83socket module for details. For Internet protocols, this is a tuple
84containing a string giving the address, and an integer port number:
85\code{('127.0.0.1', 80)}, for example.
86\end{datadesc}
87
88\begin{datadesc}{socket}
89The socket object on which the server will listen for incoming requests.
90\end{datadesc}
91
92% XXX should class variables be covered before instance variables, or
93% vice versa?
94
95The server classes support the following class variables:
96
Moshe Zadkadd802202000-12-13 20:39:22 +000097\begin{datadesc}{allow_reuse_address}
98Whether the server will allow the reuse of an address. This defaults
Raymond Hettinger7ad09552002-08-25 16:27:33 +000099to \code{False}, and can be set in subclasses to change the policy.
Moshe Zadkadd802202000-12-13 20:39:22 +0000100\end{datadesc}
101
Guido van Rossum6181e001997-05-19 19:55:16 +0000102\begin{datadesc}{request_queue_size}
103The size of the request queue. If it takes a long time to process a
104single request, any requests that arrive while the server is busy are
Fred Drakebe2b6d71998-03-14 06:40:34 +0000105placed into a queue, up to \member{request_queue_size} requests. Once
Guido van Rossum6181e001997-05-19 19:55:16 +0000106the queue is full, further requests from clients will get a
107``Connection denied'' error. The default value is usually 5, but this
108can be overridden by subclasses.
109\end{datadesc}
110
111\begin{datadesc}{socket_type}
Fred Drakebe2b6d71998-03-14 06:40:34 +0000112The type of socket used by the server; \constant{socket.SOCK_STREAM}
113and \constant{socket.SOCK_DGRAM} are two possible values.
Guido van Rossum6181e001997-05-19 19:55:16 +0000114\end{datadesc}
115
116There are various server methods that can be overridden by subclasses
Fred Drakebe2b6d71998-03-14 06:40:34 +0000117of base server classes like \class{TCPServer}; these methods aren't
Guido van Rossum6181e001997-05-19 19:55:16 +0000118useful to external users of the server object.
119
120% should the default implementations of these be documented, or should
121% it be assumed that the user will look at SocketServer.py?
122
123\begin{funcdesc}{finish_request}{}
124Actually processes the request by instantiating
Fred Drakebe2b6d71998-03-14 06:40:34 +0000125\member{RequestHandlerClass} and calling its \method{handle()} method.
Guido van Rossum6181e001997-05-19 19:55:16 +0000126\end{funcdesc}
127
128\begin{funcdesc}{get_request}{}
129Must accept a request from the socket, and return a 2-tuple containing
130the \emph{new} socket object to be used to communicate with the
131client, and the client's address.
132\end{funcdesc}
133
Fred Drakecce10901998-03-17 06:33:25 +0000134\begin{funcdesc}{handle_error}{request, client_address}
Fred Drakebe2b6d71998-03-14 06:40:34 +0000135This function is called if the \member{RequestHandlerClass}'s
136\method{handle()} method raises an exception. The default action is
137to print the traceback to standard output and continue handling
138further requests.
Guido van Rossum6181e001997-05-19 19:55:16 +0000139\end{funcdesc}
140
Fred Drakecce10901998-03-17 06:33:25 +0000141\begin{funcdesc}{process_request}{request, client_address}
Fred Drakebe2b6d71998-03-14 06:40:34 +0000142Calls \method{finish_request()} to create an instance of the
143\member{RequestHandlerClass}. If desired, this function can create a
144new process or thread to handle the request; the \class{ForkingMixIn}
145and \class{ThreadingMixIn} classes do this.
Guido van Rossum6181e001997-05-19 19:55:16 +0000146\end{funcdesc}
147
148% Is there any point in documenting the following two functions?
149% What would the purpose of overriding them be: initializing server
150% instance variables, adding new network families?
151
152\begin{funcdesc}{server_activate}{}
153Called by the server's constructor to activate the server.
154May be overridden.
155\end{funcdesc}
156
157\begin{funcdesc}{server_bind}{}
158Called by the server's constructor to bind the socket to the desired
159address. May be overridden.
160\end{funcdesc}
161
Fred Drakecce10901998-03-17 06:33:25 +0000162\begin{funcdesc}{verify_request}{request, client_address}
Guido van Rossum6181e001997-05-19 19:55:16 +0000163Must return a Boolean value; if the value is true, the request will be
164processed, and if it's false, the request will be denied.
165This function can be overridden to implement access controls for a server.
166The default implementation always return true.
167\end{funcdesc}
168
Fred Drakebe2b6d71998-03-14 06:40:34 +0000169The request handler class must define a new \method{handle()} method,
170and can override any of the following methods. A new instance is
171created for each request.
Guido van Rossum6181e001997-05-19 19:55:16 +0000172
173\begin{funcdesc}{finish}{}
Fred Drakebe2b6d71998-03-14 06:40:34 +0000174Called after the \method{handle()} method to perform any clean-up
175actions required. The default implementation does nothing. If
176\method{setup()} or \method{handle()} raise an exception, this
177function will not be called.
Guido van Rossum6181e001997-05-19 19:55:16 +0000178\end{funcdesc}
179
180\begin{funcdesc}{handle}{}
181This function must do all the work required to service a request.
182Several instance attributes are available to it; the request is
Fred Drakebe2b6d71998-03-14 06:40:34 +0000183available as \member{self.request}; the client address as
Guido van Rossumda30f4c1998-11-16 19:07:04 +0000184\member{self.client_address}; and the server instance as
Fred Drakebe2b6d71998-03-14 06:40:34 +0000185\member{self.server}, in case it needs access to per-server
186information.
Guido van Rossum6181e001997-05-19 19:55:16 +0000187
Fred Drakebe2b6d71998-03-14 06:40:34 +0000188The type of \member{self.request} is different for datagram or stream
189services. For stream services, \member{self.request} is a socket
190object; for datagram services, \member{self.request} is a string.
Guido van Rossum6181e001997-05-19 19:55:16 +0000191However, this can be hidden by using the mix-in request handler
192classes
Fred Drakebe2b6d71998-03-14 06:40:34 +0000193\class{StreamRequestHandler} or \class{DatagramRequestHandler}, which
194override the \method{setup()} and \method{finish()} methods, and
195provides \member{self.rfile} and \member{self.wfile} attributes.
196\member{self.rfile} and \member{self.wfile} can be read or written,
197respectively, to get the request data or return data to the client.
Guido van Rossum6181e001997-05-19 19:55:16 +0000198\end{funcdesc}
199
200\begin{funcdesc}{setup}{}
Fred Drakebe2b6d71998-03-14 06:40:34 +0000201Called before the \method{handle()} method to perform any
202initialization actions required. The default implementation does
203nothing.
Guido van Rossum6181e001997-05-19 19:55:16 +0000204\end{funcdesc}