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 3.3: 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, no_keep_alive=False, io_loop=None, xheaders=False, ssl_options=None, protocol=None, gzip=False, chunk_size=None, max_header_size=None, idle_connection_timeout=None, body_timeout=None, max_body_size=None, max_buffer_size=None)

A non-blocking, single-threaded HTTP server.

A server is defined by either a request callback that takes a HTTPServerRequest as an argument or a HTTPServerConnectionDelegate instance.

A simple example server that echoes back the URI you requested:

import tornado.httpserver
import tornado.ioloop

def handle_request(request):
   message = "You requested %s\n" % request.uri
   request.connection.write_headers(
       httputil.ResponseStartLine('HTTP/1.1', 200, 'OK'),
       {"Content-Length": str(len(message))})
   request.connection.write(message)
   request.connection.finish()

http_server = tornado.httpserver.HTTPServer(handle_request)
http_server.listen(8888)
tornado.ioloop.IOLoop.instance().start()

Applications should use the methods of HTTPConnection to write their response.

HTTPServer supports keep-alive connections by default (automatically for HTTP/1.1, or for HTTP/1.0 when the client requests Connection: keep-alive).

If xheaders is True, we support the X-Real-Ip/X-Forwarded-For and X-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. The protocol argument can also be set to https if Tornado is run behind an SSL-decoding proxy that does not set one of the supported xheaders.

To make this server serve SSL traffic, send the ssl_options dictionary argument with the arguments required for the ssl.wrap_socket method, including certfile and keyfile. (In Python 3.2+ you can pass an ssl.SSLContext object instead of a dict):

HTTPServer(applicaton, ssl_options={
    "certfile": os.path.join(data_dir, "mydomain.crt"),
    "keyfile": os.path.join(data_dir, "mydomain.key"),
})

HTTPServer initialization follows one of three patterns (the initialization methods are defined on tornado.tcpserver.TCPServer):

1. listen: simple single-process:

   server = HTTPServer(app)
   server.listen(8888)
   IOLoop.instance().start()
   

   In many cases, tornado.web.Application.listen can be used to avoid the need to explicitly create the HTTPServer.

2. bind/start: simple multi-process:

   server = HTTPServer(app)
   server.bind(8888)
   server.start(0)  # Forks multiple sub-processes
   IOLoop.instance().start()
   

   When using this interface, an IOLoop must not be passed to the HTTPServer constructor. start will always start the server on the default singleton IOLoop.

3. add_sockets: advanced multi-process:

   sockets = tornado.netutil.bind_sockets(8888)
   tornado.process.fork_processes(0)
   server = HTTPServer(app)
   server.add_sockets(sockets)
   IOLoop.instance().start()
   

   The add_sockets interface is more complicated, but it can be used with tornado.process.fork_processes to give you more flexibility in when the fork happens. add_sockets can also be used in single-process servers if you want to create your listening sockets in some way other than tornado.netutil.bind_sockets.

Changed in version 3.3: Added gzip, chunk_size, max_header_size, idle_connection_timeout, body_timeout, max_body_size arguments. Added support for HTTPServerConnectionDelegate instances as request_callback.