httptools: Connection: Close does not close the connection

[8dazo]

On the httptools HTTP implementation (what --http auto selects when httptools is installed), Uvicorn only honors a request Connection: close when the header value is exactly lowercase close.

Connection: Close and Connection: keep-alive, close leave the TCP connection open and do not echo Connection: close on the response. h11 and zttp close in all three cases.

This looks like a bug rather than intentional behavior:

• docs/server-behavior.md says a Connection: Close header must close the connection, and that HTTP headers are case-insensitive.
• RFC 9112 §9.6: a server that receives a close connection option MUST close after the final response, and SHOULD send Connection: close on that response. Tokens are case-insensitive (RFC 9110 §7.6.1).
• httptools already treats the response Connection value as case-insensitive (value.lower() == b"close"). The request check is an exact tuple match on (b"connection", b"close"). Existing tests only send lowercase close.

Versions

Running uvicorn 0.52.3 with CPython 3.12.13 on Darwin

Reproduced on current main.

Reproduction

import asyncio

from tests.protocols.test_http import get_connected_protocol
from tests.response import Response
from uvicorn.protocols.http.h11_impl import H11Protocol
from uvicorn.protocols.http.httptools_impl import HttpToolsProtocol
from uvicorn.protocols.http.zttp_impl import ZttpProtocol

REQUESTS = {
    "lower": b"GET / HTTP/1.1\r\nHost: example.org\r\nConnection: close\r\n\r\n",
    "upper": b"GET / HTTP/1.1\r\nHost: example.org\r\nConnection: Close\r\n\r\n",
    "mixed": b"GET / HTTP/1.1\r\nHost: example.org\r\nConnection: keep-alive, close\r\n\r\n",
}

async def main():
    for name, cls in [
        ("h11", H11Protocol),
        ("httptools", HttpToolsProtocol),
        ("zttp", ZttpProtocol),
    ]:
        for key, req in REQUESTS.items():
            protocol = get_connected_protocol(
                Response("Hello, world", media_type="text/plain"),
                cls,
                access_log=False,
            )
            protocol.data_received(req)
            await protocol.loop.run_one()
            buf = protocol.transport.buffer.lower()
            print(
                name,
                key,
                "closing=",
                protocol.transport.is_closing(),
                "echo=",
                b"connection: close" in buf,
            )

asyncio.run(main())

Actual

h11        lower   closing=True  echo=True
h11        upper   closing=True  echo=True
h11        mixed   closing=True  echo=True
httptools  lower   closing=True  echo=True
httptools  upper   closing=False echo=False
httptools  mixed   closing=False echo=False
zttp       lower   closing=True  echo=True
zttp       upper   closing=True  echo=False
zttp       mixed   closing=True  echo=False

Expected

All three implementations close after the response and echo Connection: close whenever the request Connection header contains a close token, regardless of case or sibling tokens.

Cause

CLOSE_HEADER = (b"connection", b"close")

if CLOSE_HEADER in self.scope["headers"] and CLOSE_HEADER not in headers:
    headers = headers + [CLOSE_HEADER]

Header names are lowercased; values are not. b"Close" and b"keep-alive, close" never match. httptools then never sets keep_alive = False (that flag is only flipped when writing a response connection: close header). h11 still closes via MUST_CLOSE; zttp still closes via should_close().

Question

Does this match what you’d want fixed? If so, I can open a PR that parses Connection as a comma-separated, case-insensitive token list (httptools required; h11/zttp so they also echo Connection: close for mixed-case / multi-token values), plus a regression test parametrized across implementations.

[MLuc24]

Two things worth adding, because the fix is a bit wider than the httptools request check and the obvious one-liner doesn't cover all three of your cases.

First, the exact-match constant isn't local to httptools. It's defined in flow_control.py and used identically by both implementations:

CLOSE_HEADER = (b"connection", b"close")

if CLOSE_HEADER in self.scope["headers"] and CLOSE_HEADER not in headers:
    headers = headers + [CLOSE_HEADER]

That's httptools_impl.py:481 and h11_impl.py:478, the same line. So the echo half of the bug is present in h11 too — send it Connection: Close and it won't add Connection: close to the response either. h11 still closes, as you measured, but that's its own state machine doing it rather than this line, which means the shared line governs only the echo and is wrong in both. Patching just httptools would leave h11 quietly non-compliant on the SHOULD.

Second, lowercasing alone won't fix keep-alive, close. Connection is a comma-separated token list, so the value has to be split before comparing — and the correct handling already exists a couple of hundred lines up in the same file, in _get_upgrade:

if name == b"connection":
    connection = [token.lower().strip() for token in value.split(b",")]

if b"upgrade" in connection:

Split, strip, lowercase each token, membership test. That's exactly what the close check needs, and it makes the change an argument about consistency with existing code rather than a new convention — which is usually an easier sell.

So the tidy shape is probably a small helper next to CLOSE_HEADER in flow_control.py, something like has_close_token(headers) doing that tokenisation, called from both implementations for the echo and from httptools for the keep-alive decision. One place to test, and it fixes the h11 echo at the same time.

Worth extending the test matrix past your three too — close with trailing whitespace and CLOSE uppercase both fall out of the same tokenisation, and a test that pins them stops the exact-match version creeping back.

[Yigtwxx]

Your diagnosis holds, and the shared-constant point above is right. Two more things fall out of the same line, and both are reachable today without any unusual request — worth folding into the PR so this gets fixed once.

The response side isn't actually case-insensitive, it's case-insensitive for one exact value. Your write-up says httptools already handles the response Connection correctly. It handles case, not token lists:

elif name == b"connection" and value.lower() == b"close":
    self.keep_alive = False

httptools_impl.py:510. An application returning Connection: keep-alive, close — perfectly legal, same shape as the request case you're fixing — lowercases to b"keep-alive, close", which isn't equal to b"close", so keep_alive stays True. The header goes out on the wire telling the client the connection is closing, and Uvicorn then keeps the socket open. That's the mirror of the bug you reported, on a path that doesn't involve the request at all.

It also explains why the two halves aren't independent. The only thing that flips keep_alive on the httptools path is this loop reading a response header. The CLOSE_HEADER line at :481 isn't just the echo — it's the mechanism by which a request Connection: close reaches the close decision at all, by manufacturing a response header for :510 to find. Fixing the request check without fixing :510 leaves a second way to get an advertised-but-not-performed close.

The dedupe guard on that same line has an exact-match bug of its own:

if CLOSE_HEADER in self.scope["headers"] and CLOSE_HEADER not in headers:
    headers = headers + [CLOSE_HEADER]

headers here is self.default_headers + list(message.get("headers", [])) — raw ASGI headers, not yet normalized. Names are only lowercased further down, inside the write loop. So an app that already set (b"Connection", b"close") or (b"connection", b"Close") fails the not in test, and Uvicorn appends a second connection: close. The response goes out with two Connection header lines. This one fires on your lowercase request case, the one that currently reports as working — it just needs the app to have set the header itself with different casing.

So there are three comparisons against the same concept, each wrong in a different way: exact-match on the request, exact-match on the app's headers, single-token equality on the response. A helper next to CLOSE_HEADER in flow_control.py doing the _get_upgrade tokenisation, called from all three, collapses them:

def has_close_token(headers: list[tuple[bytes, bytes]]) -> bool:
    for name, value in headers:
        if name.lower() == b"connection":
            if b"close" in (token.strip() for token in value.lower().split(b",")):
                return True
    return False

Request side and app-header dedupe both become has_close_token(...), and :510 becomes a token check on the value it already has.

Two cases for the matrix beyond the ones already suggested. An app response of Connection: keep-alive, close, asserting the transport actually closes. And a request with Connection: keep-alive plus a separate Connection: close line — RFC 9110 §5.3 permits repeated field lines, and a helper that iterates all headers handles it while one that stops at the first connection match does not.

Small thing on your reproducer table: zttp shows echo=False for upper and mixed too, so the echo fix isn't httptools-and-h11 only. It closes via should_close() for the same reason h11 does, independently of this line, which is why only the echo column shows the problem there.

[Kludex]

I merged a fix.