tornado.httpserver
— Non-blocking HTTP server¶
A non-blocking, single-threaded HTTP server.
Typical applications have little direct interaction with the HTTPServer
class except to start a server at the beginning of the process
(and even that is often done indirectly via tornado.web.Application.listen
).
Changed in version 4.0: The HTTPRequest
class that used to live in this module has been moved
to tornado.httputil.HTTPServerRequest
. The old name remains as an alias.
HTTP Server¶
- class tornado.httpserver.HTTPServer(request_callback: Union[httputil.HTTPServerConnectionDelegate, Callable[[httputil.HTTPServerRequest], None]], no_keep_alive: bool = False, xheaders: bool = False, ssl_options: Union[Dict[str, Any], ssl.SSLContext] = None, protocol: Optional[str] = None, decompress_request: bool = False, chunk_size: Optional[int] = None, max_header_size: Optional[int] = None, idle_connection_timeout: Optional[float] = None, body_timeout: Optional[float] = None, max_body_size: Optional[int] = None, max_buffer_size: Optional[int] = None, trusted_downstream: Optional[List[str]] = None)[source]¶
A non-blocking, single-threaded HTTP server.
A server is defined by a subclass of
HTTPServerConnectionDelegate
, or, for backwards compatibility, a callback that takes anHTTPServerRequest
as an argument. The delegate is usually atornado.web.Application
.HTTPServer
supports keep-alive connections by default (automatically for HTTP/1.1, or for HTTP/1.0 when the client requestsConnection: keep-alive
).If
xheaders
isTrue
, we support theX-Real-Ip
/X-Forwarded-For
andX-Scheme
/X-Forwarded-Proto
headers, which override the remote IP and URI scheme/protocol for all requests. These headers are useful when running Tornado behind a reverse proxy or load balancer. Theprotocol
argument can also be set tohttps
if Tornado is run behind an SSL-decoding proxy that does not set one of the supportedxheaders
.By default, when parsing the
X-Forwarded-For
header, Tornado will select the last (i.e., the closest) address on the list of hosts as the remote host IP address. To select the next server in the chain, a list of trusted downstream hosts may be passed as thetrusted_downstream
argument. These hosts will be skipped when parsing theX-Forwarded-For
header.To make this server serve SSL traffic, send the
ssl_options
keyword argument with anssl.SSLContext
object. For compatibility with older versions of Pythonssl_options
may also be a dictionary of keyword arguments for thessl.wrap_socket
method.:ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) ssl_ctx.load_cert_chain(os.path.join(data_dir, "mydomain.crt"), os.path.join(data_dir, "mydomain.key")) HTTPServer(application, ssl_options=ssl_ctx)
HTTPServer
initialization follows one of three patterns (the initialization methods are defined ontornado.tcpserver.TCPServer
):listen
: single-process:async def main(): server = HTTPServer() server.listen(8888) await asyncio.Event.wait() asyncio.run(main())
In many cases,
tornado.web.Application.listen
can be used to avoid the need to explicitly create theHTTPServer
.While this example does not create multiple processes on its own, when the
reuse_port=True
argument is passed tolisten()
you can run the program multiple times to create a multi-process service.add_sockets
: multi-process:sockets = bind_sockets(8888) tornado.process.fork_processes(0) async def post_fork_main(): server = HTTPServer() server.add_sockets(sockets) await asyncio.Event().wait() asyncio.run(post_fork_main())
The
add_sockets
interface is more complicated, but it can be used withtornado.process.fork_processes
to run a multi-process service with all worker processes forked from a single parent.add_sockets
can also be used in single-process servers if you want to create your listening sockets in some way other thanbind_sockets
.Note that when using this pattern, nothing that touches the event loop can be run before
fork_processes
.bind
/start
: simple deprecated multi-process:server = HTTPServer() server.bind(8888) server.start(0) # Forks multiple sub-processes IOLoop.current().start()
This pattern is deprecated because it requires interfaces in the
asyncio
module that have been deprecated since Python 3.10. Support for creating multiple processes in thestart
method will be removed in a future version of Tornado.
Changed in version 4.0: Added
decompress_request
,chunk_size
,max_header_size
,idle_connection_timeout
,body_timeout
,max_body_size
arguments. Added support forHTTPServerConnectionDelegate
instances asrequest_callback
.Changed in version 4.1:
HTTPServerConnectionDelegate.start_request
is now called with two arguments(server_conn, request_conn)
(in accordance with the documentation) instead of one(request_conn)
.Changed in version 4.2:
HTTPServer
is now a subclass oftornado.util.Configurable
.Changed in version 4.5: Added the
trusted_downstream
argument.Changed in version 5.0: The
io_loop
argument has been removed.The public interface of this class is mostly inherited from
TCPServer
and is documented under that class.- coroutine close_all_connections() None [source]¶
Close all open connections and asynchronously wait for them to finish.
This method is used in combination with
stop
to support clean shutdowns (especially for unittests). Typical usage would callstop()
first to stop accepting new connections, thenawait close_all_connections()
to wait for existing connections to finish.This method does not currently close open websocket connections.
Note that this method is a coroutine and must be called with
await
.