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()
->  while True:
        tick()
        # This blocks until a request comes in:
        child = socket.accept()
        conn = HTTPConnection(child, ...)
        server.requests.put(conn)

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.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. Return success.

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.HTTPConnection(server, sock, makefile=<function MakeFile_PY3>)

Bases: object

An HTTP connection (active socket).

RequestHandlerClass

alias of HTTPRequest

close()

Close the socket underlying this connection.

communicate()

Read each request and respond appropriately.

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
linger = False
peer_gid

Return the group id of the connected peer process.

peer_group

Return the group of the connected peer process.

peer_pid

Return the id of the connected peer process.

peer_uid

Return the user id of the connected peer process.

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()

Return the username and group tuple of the peercreds if available.

Raises:
NotImplementedError: in case of unsupported OS RuntimeError: in case of UID/GID lookup unsupported or disabled
ssl_env = None
wbufsize = 8192
class cheroot.server.HTTPServer(bind_addr, gateway, minthreads=10, maxthreads=-1, server_name=None, peercreds_enabled=False, peercreds_resolve_enabled=False)

Bases: object

An HTTP server.

ConnectionClass

The class to use for handling HTTP connections.

alias of HTTPConnection

bind(family, type, proto=0)

Create (or recreate) the actual socket object.

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 filename as a string.

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

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
gateway = None

A Gateway instance.

interrupt

Flag interrupt of the server.

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 cred lookup can be performed via UNIX domain socket.

peercreds_resolve_enabled = False

If True, username/group will be looked up in the OS from peercreds.

prepare()

Prepare server to serving requests.

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

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.

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

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

You must have the corresponding SSL 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.

tick()

Accept a new connection and put it on the Queue.

timeout = 10

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

version = 'Cheroot/6.4.1.dev1+g111e9f5.d20180801'

A version string for the HTTPServer.

class cheroot.server.SizeCheckWrapper(rfile, maxlen)

Bases: object

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

close()

Release resources allocated for rfile.

next()

Generate next file chunk.

read(size=None)

Read a chunk from rfile buffer and return it.

Args:
size (int): amount of data to read
Returns:
bytes: Chunk from rfile, limited by size if specified.
readline(size=None)

Read a single line from rfile buffer and return it.

Args:
size (int): minimum amount of data to read
Returns:
bytes: One line from rfile.
readlines(sizehint=0)

Read all lines from rfile buffer and return them.

Args:
sizehint (int): hint of minimum amount of data to read
Returns:
list[bytes]: Lines of bytes read from rfile.
class cheroot.server.KnownLengthRFile(rfile, content_length)

Bases: object

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

close()

Release resources allocated for rfile.

next()

Generate next file chunk.

read(size=None)

Read a chunk from rfile buffer and return it.

Args:
size (int): amount of data to read
Returns:
bytes: Chunk from rfile, limited by size if specified.
readline(size=None)

Read a single line from rfile buffer and return it.

Args:
size (int): minimum amount of data to read
Returns:
bytes: One line from rfile.
readlines(sizehint=0)

Read all lines from rfile buffer and return them.

Args:
sizehint (int): hint of minimum amount of data to read
Returns:
list[bytes]: Lines of bytes read from rfile.
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.

close()

Release resources allocated for rfile.

read(size=None)

Read a chunk from rfile buffer and return it.

Args:
size (int): amount of data to read
Returns:
bytes: Chunk from rfile, limited by size if specified.
read_trailer_lines()

Read HTTP headers and yield them.

Returns:
Generator: yields CRLF separated lines.
readline(size=None)

Read a single line from rfile buffer and return it.

Args:
size (int): minimum amount of data to read
Returns:
bytes: One line from rfile.
readlines(sizehint=0)

Read all lines from rfile buffer and return them.

Args:
sizehint (int): hint of minimum amount of data to read
Returns:
list[bytes]: Lines of bytes read from rfile.
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.

cheroot.server.get_ssl_adapter_class(name='builtin')

Return an SSL adapter class for the given name.

Indices and tables