cheroot.server module#

A high-speed, production ready, thread pooled, generic HTTP server.

For those of you wanting to understand internals of this module, here’s the basic call flow. The server’s listening thread runs a very tight loop, sticking incoming connections onto a Queue:

server = HTTPServer(...)
server.start()
->  serve()
    while ready:
        _connections.run()
            while not stop_requested:
                child = socket.accept()  # blocks until a request comes in
                conn = HTTPConnection(child, ...)
                server.process_conn(conn)  # adds conn to threadpool

Worker threads are kept in a pool and poll the Queue, popping off and then handling each connection in turn. Each connection can consist of an arbitrary number of requests and their responses, so we run a nested loop:

while True:
    conn = server.requests.get()
    conn.communicate()
    ->  while True:
            req = HTTPRequest(...)
            req.parse_request()
            ->  # Read the Request-Line, e.g. "GET /page HTTP/1.1"
                req.rfile.readline()
                read_headers(req.rfile, req.inheaders)
            req.respond()
            ->  response = app(...)
                try:
                    for chunk in response:
                        if chunk:
                            req.write(chunk)
                finally:
                    if hasattr(response, "close"):
                        response.close()
            if req.close_connection:
                return

For running a server you can invoke start() (it will run the server forever) or use invoking prepare() and serve() like this:

server = HTTPServer(...)
server.prepare()
try:
    threading.Thread(target=server.serve).start()

    # waiting/detecting some appropriate stop condition here
    ...

finally:
    server.stop()

And now for a trivial doctest to exercise the test suite

>>> 'HTTPServer' in globals()
True

class cheroot.server.ChunkedRFile(rfile, maxlen, bufsize=8192)#

Bases: object

Wraps a file-like object, returning an empty string when exhausted.

This class is intended to provide a conforming wsgi.input value for request entities that have been encoded with the ‘chunked’ transfer encoding.

Parameters

rfile – file encoded with the ‘chunked’ transfer encoding
maxlen (int) – maximum length of the file being read
bufsize (int) – size of the buffer used to read the file

_fetch()#

close()#: Release resources allocated for rfile.

read(size=None)#

Read a chunk from rfile buffer and return it.

Parameters: size (int) – amount of data to read
Returns: chunk from rfile, limited by size if specified
Return type: bytes

read_trailer_lines()#

Read HTTP headers and yield them.

Yields: CRLF separated lines
Ytype: bytes

readline(size=None)#

Read a single line from rfile buffer and return it.

Parameters: size (int) – minimum amount of data to read
Returns: one line from rfile
Return type: bytes

readlines(sizehint=0)#

Read all lines from rfile buffer and return them.

Parameters: sizehint (int) – hint of minimum amount of data to read
Returns: lines of bytes read from rfile
Return type: list[bytes]

class cheroot.server.DropUnderscoreHeaderReader#

Bases: cheroot.server.HeaderReader

Custom HeaderReader to exclude any headers with underscores in them.

_allow_header(key_name)#

class cheroot.server.Gateway(req)#

Bases: object

Base class to interface HTTPServer with other systems, such as WSGI.

respond()#: Process the current request. Must be overridden in a subclass.

class cheroot.server.HTTPConnection(server, sock, makefile=<function MakeFile>)#

Bases: object

An HTTP connection (active socket).

RequestHandlerClass#: alias of cheroot.server.HTTPRequest

_close_kernel_socket()#: Terminate the connection at the transport level.

_conditional_error(req, response)#

Respond with an error.

Don’t bother writing if a response has already started being written.

_handle_no_ssl(req)#

close()#: Close the socket underlying this connection.

communicate()#

Read each request and respond appropriately.

Returns true if the connection should be kept open.

get_peer_creds()#

Return the PID/UID/GID tuple of the peer socket for UNIX sockets.

This function uses SO_PEERCRED to query the UNIX PID, UID, GID of the peer, which is only available if the bind address is a UNIX domain socket.

Raises:: NotImplementedError: in case of unsupported socket type RuntimeError: in case of SO_PEERCRED lookup unsupported or disabled

last_used = None#

linger = False#

property peer_gid#: Return the group id of the connected peer process.

property peer_group#: Return the group of the connected peer process.

property peer_pid#: Return the id of the connected peer process.

property peer_uid#: Return the user id of the connected peer process.

property peer_user#: Return the username of the connected peer process.

peercreds_enabled = False#

peercreds_resolve_enabled = False#

rbufsize = 8192#

remote_addr = None#

remote_port = None#

resolve_peer_creds()#

Look up the username and group tuple of the PEERCREDS.

Returns

the username and group tuple of the PEERCREDS

Raises

NotImplementedError – if the OS is unsupported
RuntimeError – if UID/GID lookup is unsupported or disabled

ssl_env = None#

wbufsize = 8192#

class cheroot.server.HTTPRequest(server, conn, proxy_mode=False, strict_mode=True)#

Bases: object

An HTTP Request (and response).

A single HTTP connection may consist of multiple request/response pairs.

chunked_write = False#

If True, output will be encoded with the “chunked” transfer-coding.

This value is set automatically inside send_headers.

close_connection = False#: Signals the calling Connection that the request should close. This does not imply an error! The client and/or server may each request that the connection be closed.

conn = None#: The HTTPConnection object on which this request connected.

ensure_headers_sent()#: Ensure headers are sent to the client if not already sent.

header_reader = <cheroot.server.HeaderReader object>#: A HeaderReader instance or compatible reader.

inheaders = {}#: A dict of request headers.

outheaders = []#: A list of header tuples to write in the response.

parse_request()#: Parse the next HTTP request start-line and message-headers.

read_request_headers()#

Read self.rfile into self.inheaders.

Ref: self.inheaders.

Returns: success status
Return type: bool

read_request_line()#

Read and parse first line of the HTTP request.

Returns:: bool: True if the request line is valid or False if it’s malformed.

ready = False#: When True, the request has been parsed and is ready to begin generating the response. When False, signals the calling Connection that the response should not be generated and the connection should close.

respond()#: Call the gateway and write its iterable output.

send_headers()#

Assert, process, and send the HTTP response message-headers.

You must set self.status, and self.outheaders before calling this.

server = None#: The HTTPServer object which is receiving this request.

simple_response(status, msg='')#: Write a simple response back to the client.

write(chunk)#: Write unbuffered data to the client.

class cheroot.server.HTTPServer(bind_addr, gateway, minthreads=10, maxthreads=- 1, server_name=None, peercreds_enabled=False, peercreds_resolve_enabled=False, reuse_port=False)#

Bases: object

An HTTP server.

ConnectionClass#

The class to use for handling HTTP connections.

alias of cheroot.server.HTTPConnection

_bind_addr = '127.0.0.1'#

_interrupt = None#

static _make_socket_reusable(socket_, bind_addr)#

_run_in_thread()#: Context manager for running this server in a thread.

property _stopping_for_interrupt#: Return whether the server is responding to an interrupt.

bind(family, type, proto=0)#: Create (or recreate) the actual socket object.

property bind_addr#

Return the interface on which to listen for connections.

For TCP sockets, a (host, port) tuple. Host values may be any IPv4 or IPv6 address, or any valid hostname. The string ‘localhost’ is a synonym for ‘127.0.0.1’ (or ‘::1’, if your hosts file prefers IPv6). The string ‘0.0.0.0’ is a special IPv4 entry meaning “any active interface” (INADDR_ANY), and ‘::’ is the similar IN6ADDR_ANY for IPv6. The empty string or None are not allowed.

For UNIX sockets, supply the file name as a string.

Systemd socket activation is automatic and doesn’t require tempering with this variable.

IPv4#: Internet Protocol version 4
IPv6#: Internet Protocol version 6

static bind_socket(socket_, bind_addr)#: Bind the socket to given interface.

bind_unix_socket(bind_addr)#: Create (or recreate) a UNIX socket object.

property can_add_keepalive_connection#: Flag whether it is allowed to add a new keep-alive connection.

clear_stats()#: Reset server stat counters..

error_log(msg='', level=20, traceback=False)#

Write error message to log.

Args:: msg (str): error message level (int): logging level traceback (bool): add traceback to output or not

expiration_interval = 0.5#: The interval, in seconds, at which the server checks for expired connections (default 0.5).

gateway = None#: A Gateway instance.

property interrupt#: Flag interrupt of the server.

keep_alive_conn_limit = 10#

Maximum number of waiting keep-alive connections that will be kept open.

Default is 10. Set to None to have unlimited connections.

max_request_body_size = 0#: The maximum size, in bytes, for request bodies, or 0 for no limit.

max_request_header_size = 0#: The maximum size, in bytes, for request headers, or 0 for no limit.

maxthreads = None#

The maximum number of worker threads to create.

(default -1 = no limit)

minthreads = None#: The minimum number of worker threads to create (default 10).

nodelay = True#: If True (the default since 3.1), sets the TCP_NODELAY socket option.

peercreds_enabled = False#: If True, peer creds will be looked up via UNIX domain socket.

peercreds_resolve_enabled = False#: If True, username/group will be looked up in the OS from PEERCREDS-provided IDs.

prepare()#

Prepare server to serving requests.

It binds a socket’s port, setups the socket to listen() and does other preparing things.

classmethod prepare_socket(bind_addr, family, type, proto, nodelay, ssl_adapter, reuse_port=False)#: Create and prepare the socket object.

process_conn(conn)#: Process an incoming HTTPConnection.

protocol = 'HTTP/1.1'#

The version string to write in the Status-Line of all HTTP responses.

For example, “HTTP/1.1” is the default. This also limits the supported features used in the response.

put_conn(conn)#: Put an idle connection back into the ConnectionManager.

ready = False#: Internal flag which indicating the socket is accepting connections.

request_queue_size = 5#

The ‘backlog’ arg to socket.listen(); max queued connections.

(default 5).

static resolve_real_bind_addr(socket_)#: Retrieve actual bind address from bound socket.

reuse_port = False#: If True, set SO_REUSEPORT on the socket.

runtime()#: Return server uptime.

safe_start()#: Run the server forever, and stop it cleanly on exit.

serve()#: Serve requests, after invoking prepare().

server_name = None#: The name of the server; defaults to self.version.

shutdown_timeout = 5#

The total time to wait for worker threads to cleanly exit.

Specified in seconds.

software = None#

The value to set for the SERVER_SOFTWARE entry in the WSGI environ.

If None, this defaults to '%s Server' % self.version.

ssl_adapter = None#

An instance of ssl.Adapter (or a subclass).

Ref: ssl.Adapter.

You must have the corresponding TLS driver library installed.

start()#

Run the server forever.

It is shortcut for invoking prepare() then serve().

stop()#: Gracefully shutdown a server that is serving forever.

timeout = 10#: The timeout in seconds for accepted connections (default 10).

version = 'Cheroot/10.0.1.dev25+g00c3cc3'#: A version string for the HTTPServer.

class cheroot.server.HeaderReader#

Bases: object

Object for reading headers from an HTTP request.

Interface and default implementation.

_allow_header(key_name)#

_transform_key(key_name)#

class cheroot.server.KnownLengthRFile(rfile, content_length)#

Bases: object

Wraps a file-like object, returning an empty string when exhausted.

Parameters

rfile – file of a known size
content_length (int) – length of the file being read

close()#: Release resources allocated for rfile.

next()#: Generate next file chunk.

read(size=None)#

Read a chunk from rfile buffer and return it.

Parameters: size (int) – amount of data to read
Return type: bytes
Returns: chunk from rfile, limited by size if specified

readline(size=None)#

Read a single line from rfile buffer and return it.

Parameters: size (int) – minimum amount of data to read
Returns: one line from rfile
Return type: bytes

readlines(sizehint=0)#

Read all lines from rfile buffer and return them.

Parameters: sizehint (int) – hint of minimum amount of data to read
Returns: lines of bytes read from rfile
Return type: list[bytes]

class cheroot.server.SizeCheckWrapper(rfile, maxlen)#

Bases: object

Wraps a file-like object, raising MaxSizeExceeded if too large.

Parameters

rfile – file of a limited size
maxlen (int) – maximum length of the file being read

_check_length()#

close()#: Release resources allocated for rfile.

next()#: Generate next file chunk.

read(size=None)#

Read a chunk from rfile buffer and return it.

Parameters: size (int) – amount of data to read
Returns: chunk from rfile, limited by size if specified
Return type: bytes

readline(size=None)#

Read a single line from rfile buffer and return it.

Parameters: size (int) – minimum amount of data to read
Returns: one line from rfile
Return type: bytes

readlines(sizehint=0)#

Read all lines from rfile buffer and return them.

Parameters: sizehint (int) – hint of minimum amount of data to read
Returns: lines of bytes read from rfile
Return type: list[bytes]

cheroot.server.get_ssl_adapter_class(name='builtin')#: Return an SSL adapter class for the given name.