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
- _fetch()#
- close()#
Release resources allocated for
rfile
.
- read(size=None)#
Read a chunk from
rfile
buffer and return it.
- 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.
- 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
intoself.inheaders
.Ref:
self.inheaders
.- Returns
success status
- Return type
- 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
, andself.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.
- 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_resolve_enabled = False#
If
True
, username/group will be looked up in the OS fromPEERCREDS
-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.
- 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.
- 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 sizecontent_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.
- readline(size=None)#
Read a single line from
rfile
buffer and return it.
- class cheroot.server.SizeCheckWrapper(rfile, maxlen)#
Bases:
object
Wraps a file-like object, raising MaxSizeExceeded if too large.
- Parameters
rfile –
file
of a limited sizemaxlen (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.
- readline(size=None)#
Read a single line from
rfile
buffer and return it.
- cheroot.server.get_ssl_adapter_class(name='builtin')#
Return an SSL adapter class for the given name.