[Triage] ASGI worker never enforces --keep-alive: idle connections are kept open indefinitely

[mihaiblidaru]

Type

Bug Report

Description

With the asgi worker class, the --keep-alive (keepalive) setting has no effect: an idle keep-alive connection is never closed by the server. The gthread and gevent workers, same gunicorn version and same setting, close the idle connection after the configured 2 seconds.

Expected

The server closes the idle connection about 2 seconds after the response, so the second request (sent after 5 s idle) needs a new connection, as happens with the gthread and gevent workers.

Analysis

In gunicorn/asgi/protocol.py, ASGIProtocol._handle_connection arms the keep-alive timer at the end of a loop iteration and cancels it at the start of the next one. There is no await between the two, so the timer is always cancelled synchronously right after being armed, before the loop suspends in _request_ready.wait():

while not self._closed:
    self.req_count += 1
    self._cancel_keepalive_timer()          # <- cancels the timer armed a few lines below

    if not self._request_ready.is_set():
        await self._request_ready.wait()    # <- idle wait, no timer running
    ...
    keepalive = await self._handle_http_request(request, sockname, effective_peer)
    ...
    if not self._request_ready.is_set():
        self._arm_keepalive_timer()         # <- armed here, cancelled on the next iteration

_keepalive_timeout (which just calls _close_transport()) therefore never fires while a connection is idle between requests. cfg.keepalive is still honoured as a boolean (if not self.cfg.keepalive: break), but not as a timeout.

Steps to Reproduce (for bugs)

Dependencies: pip install "gunicorn[fast]" quart flask gevent urllib3

app_quart.py

import quart

app = quart.Quart(__name__)


@app.route('/')
async def index():
  return 'ok'

app_flask.py

import flask

app = flask.Flask(__name__)


@app.route('/')
def index():
  return 'ok'

check_keepalive_urllib3.py

"""Two requests over one urllib3 pool, with an idle pause longer than the server keep-alive timeout.

urllib3 debug logging shows what happens to the pooled connection:
  - server enforces keep-alive -> "Resetting dropped connection" before the second request
  - server does NOT enforce it -> the first connection is silently reused (nothing logged)
"""
import logging
import sys
import time

import urllib3

port = int(sys.argv[1])
idle = float(sys.argv[2]) if len(sys.argv) > 2 else 5.0

logging.basicConfig(level = logging.DEBUG, format = '%(asctime)s.%(msecs)03d %(name)s: %(message)s', datefmt = '%H:%M:%S')


class Collector(logging.Handler):
  messages = []

  def emit(self, record):
    self.messages.append(record.getMessage())


logging.getLogger('urllib3').addHandler(Collector())

pool = urllib3.HTTPConnectionPool('127.0.0.1', port, maxsize = 1)

r = pool.request('GET', '/', headers = {'Connection': 'keep-alive'})
print(f'request 1 -> {r.status}')

print(f'sleeping {idle:.0f} s (server keep-alive timeout is expected to be shorter) ...')
time.sleep(idle)

Collector.messages.clear()
r = pool.request('GET', '/', headers = {'Connection': 'keep-alive'})
print(f'request 2 -> {r.status}')

reconnected = any('Resetting dropped connection' in m or 'Starting new HTTP connection' in m for m in Collector.messages)

if reconnected:
  print('RESULT: the server had closed the idle connection, urllib3 reconnected -> keep-alive timeout enforced')
else:
  print('RESULT: the idle connection was still open and got reused -> server did NOT enforce its keep-alive timeout')
  sys.exit(1)

The client sends two GET / over one urllib3 connection pool with a 5 s idle pause in between, with urllib3 debug logging enabled. When the server has closed the pooled connection during the pause, urllib3 logs Resetting dropped connection before the second request; when the connection is still open it is reused silently, and the script exits with status 1.

Run the asgi worker with a 2 s keep-alive timeout and check:

gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k asgi app_quart:app & PID=$!; sleep 5
python check_keepalive_urllib3.py 18700 5
kill $PID; wait $PID

Control runs, same setting, WSGI workers:

gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k gthread app_flask:app & PID=$!; sleep 5
python check_keepalive_urllib3.py 18700 5
kill $PID; wait $PID

gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k gevent app_flask:app & PID=$!; sleep 5
python check_keepalive_urllib3.py 18700 5
kill $PID; wait $PID

Configuration

# reproduction
gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k asgi app_quart:app
# control runs
gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k gthread app_flask:app
gunicorn -b 127.0.0.1:18700 -w 1 --keep-alive 2 -k gevent app_flask:app

Logs / Error Output

gunicorn 26.2.1, quart 0.20.0, flask 3.1.3
== asgi-worker + Quart
18:34:22.401 urllib3.connectionpool: Starting new HTTP connection (1): 127.0.0.1:18710
request 1 -> 200
sleeping 5 s (server keep-alive timeout is expected to be shorter) ...
request 2 -> 200
RESULT: the idle connection was still open and got reused -> server did NOT enforce its keep-alive timeout
== gthread-worker + Flask (control)
18:34:29.044 urllib3.connectionpool: Starting new HTTP connection (1): 127.0.0.1:18710
18:34:34.051 urllib3.connectionpool: Resetting dropped connection: 127.0.0.1
request 1 -> 200
sleeping 5 s (server keep-alive timeout is expected to be shorter) ...
request 2 -> 200
RESULT: the server had closed the idle connection, urllib3 reconnected -> keep-alive timeout enforced
== gevent-worker + Flask (control)
18:34:35.269 urllib3.connectionpool: Starting new HTTP connection (1): 127.0.0.1:18710
18:34:40.277 urllib3.connectionpool: Resetting dropped connection: 127.0.0.1
request 1 -> 200
sleeping 5 s (server keep-alive timeout is expected to be shorter) ...
request 2 -> 200
RESULT: the server had closed the idle connection, urllib3 reconnected -> keep-alive timeout enforced

Gunicorn Version

gunicorn (version 26.2.1), installed from the 26.2.1 tag tarball (gunicorn_h1c 0.6.9, uvloop 0.22.1)

Python Version

Python 3.12

Worker Class

asgi (beta)

Operating System

RHEL 8 (Linux 4.18)

Additional Context

Also in the environment: Quart 0.20.0 (ASGI app), Flask 3.1.3 (WSGI app for the control runs), urllib3 (client).

Suggested fix

Arm the timer before suspending in _request_ready.wait(), only when the connection is idle between requests (not for the first request of a fresh connection), and cancel it once a request has arrived instead of unconditionally at the top of the loop. Waking the loop from _keepalive_timeout lets it notice _closed and exit right away.

Patch against 26.2.1, tested locally:

--- a/gunicorn/asgi/protocol.py
+++ b/gunicorn/asgi/protocol.py
@@ -859,6 +859,8 @@
     def _keepalive_timeout(self):
         """Called when keepalive timeout expires."""
         self._close_transport()
+        # Wake up _handle_connection so it notices _closed and exits
+        self._request_ready.set()
 
     def connection_lost(self, exc):
         """Called when the connection is lost or closed.
@@ -987,15 +989,18 @@
 
             while not self._closed:
                 self.req_count += 1
-                self._cancel_keepalive_timer()
 
                 # Wait for headers to be parsed (callback sets the event and _current_request)
                 # Don't clear if request already arrived (data_received ran before us)
                 if not self._request_ready.is_set():
+                    # Idle between requests: the keepalive timer must run while we wait
+                    if self.req_count > 1:
+                        self._arm_keepalive_timer()
                     try:
                         await self._request_ready.wait()
                     except asyncio.CancelledError:
                         break
+                self._cancel_keepalive_timer()
 
                 if self._closed or self._current_request is None:
                     break
@@ -1073,10 +1078,6 @@
                     if not self._feed_callback_parser(pipelined):
                         break
 
-                # Arm the idle keepalive timer only when nothing is ready yet;
-                # a fully pipelined request is processed on the next iteration.
-                if not self._request_ready.is_set():
-                    self._arm_keepalive_timer()
 
         except asyncio.CancelledError:
             pass

With this patch the reproduction steps above report Resetting dropped connection for the asgi worker too, i.e. the idle connection is closed after 2 s. One quirk I found is what happens if the connection is opened but stays idle before the first request. With gthread and asgi, the request is served correctly. With the gevent worker, the connection is dropped by the server. With or without the proposed patch, ASGI behaves the same as the gthread worker: the request is served correctly.

Impact

Idle client connections are only ever closed by the client. Nothing bounds the number of idle keep-alive connections a worker accumulates except the process file descriptor limit. Reproduced with a simulated abnormally low file descriptor limit (ulimit -n 40): after 23 idle keep-alive connections the next client connection is reset, and since the idle ones never expire the worker does not recover on its own.

Related

• Discussion [Triage] ASGI worker ignores configured `keepalive` with Django ASGI apps (closes idle connections immediately) #3655 (open, no replies): the asgi worker ignoring keepalive with Django, but with the opposite symptom (idle connections closed immediately). It also states that a bare ASGI app kept the connection for the configured 30 s; that part does not reproduce here on 26.0.0 or 26.2.1, with either the asyncio or the uvloop event loop, the idle connection is never closed.
• Discussion Native ASGI worker leaks active connection count and delays SIGTERM shutdown[Triage] #3659 (open): nr_conns not decremented by the asgi worker when the server closes a transport.
• PR add max_connection for asgi #3511 (open): adds a connection limit to the asgi worker; today worker_connections is not enforced by it. Current connection limit is set by the process file descriptor limit.
• master as of 2026-09-06 (commit 5212b36) still arms and cancels the keepalive timer in the same order as 26.2.1, so the bug is not fixed there either.

Checklist

• I have searched existing discussions and issues for duplicates
• I have checked the documentation and FAQ

[mihaiblidaru]

Opened #3735 with the fix and a regression test.