# `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 `tornado4.web.Application.listen`).

Changed in version 4.0: The `HTTPRequest` class that used to live in this module has been moved to `tornado4.httputil.HTTPServerRequest`. The old name remains as an alias.

## HTTP Server

class `tornado.httpserver.``HTTPServer`(*args, **kwargs)

  A non-blocking, single-threaded HTTP server.

  A server is defined by a subclass of `HTTPServerConnectionDelegate`, or, for backwards compatibility, a callback that takes an `HTTPServerRequest` as an argument. The delegate is usually a `tornado4.web.Application`.

  `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`.

  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 the `trusted_downstream` argument. These hosts will be skipped when parsing the `X-Forwarded-For` header.

  To make this server serve SSL traffic, send the `ssl_options` keyword argument with an `ssl.SSLContext` object. For compatibility with older versions of Python `ssl_options` may also be a dictionary of keyword arguments for the `ssl.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(applicaton, ssl_options=ssl_ctx)

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

  1. `listen`: simple single-process:

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

     In many cases, `tornado4.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.current().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 = tornado4.netutil.bind_sockets(8888)
         tornado4.process.fork_processes(0)
         server = HTTPServer(app)
         server.add_sockets(sockets)
         IOLoop.current().start()

     The `add_sockets` interface is more complicated, but it can be used with `tornado4.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 `tornado4.netutil.bind_sockets`.

  Changed in version 4.0: Added `decompress_request`, `chunk_size`, `max_header_size`, `idle_connection_timeout`, `body_timeout`, `max_body_size` arguments. Added support for `HTTPServerConnectionDelegate` instances as `request_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 of `tornado4.util.Configurable`.

  Changed in version 4.5: Added the `trusted_downstream` argument.

  `initialize`(request_callback, no_keep_alive=False, io_loop=None, xheaders=False, ssl_options=None, protocol=None, decompress_request=False, chunk_size=None, max_header_size=None, idle_connection_timeout=None, body_timeout=None, max_body_size=None, max_buffer_size=None, trusted_downstream=None)

    Initialize a `Configurable` subclass instance.

    Configurable classes should use `initialize` instead of `__init__`.

    Changed in version 4.2: Now accepts positional arguments in addition to keyword arguments.

  classmethod `configurable_base`()

    Returns the base class of a configurable hierarchy.

    This will normally return the class in which it is defined. (which is not necessarily the same as the cls classmethod parameter).

  classmethod `configurable_default`()

    Returns the implementation class to be used if none is configured.

  `handle_stream`(stream, address)

    Override to handle a new `IOStream` from an incoming connection.

    This method may be a coroutine; if so any exceptions it raises asynchronously will be logged. Accepting of incoming connections will not be blocked by this coroutine.

    If this `TCPServer` is configured for SSL, `handle_stream` may be called before the SSL handshake has completed. Use `SSLIOStream.wait_for_handshake` if you need to verify the client’s certificate or use NPN/ALPN.

    Changed in version 4.2: Added the option for this method to be a coroutine.

  `start_request`(server_conn, request_conn)

    This method is called by the server when a new request has started.

    Parameters:

    - server_conn – is an opaque object representing the long-lived (e.g. tcp-level) connection.
    - request_conn – is a `HTTPConnection` object for a single request/response exchange.

    This method should return a `HTTPMessageDelegate`.

  `on_close`(server_conn)

    This method is called when a connection has been closed.

    Parameters: | server_conn – is a server connection that has previously been passed to `start_request`.