What the agent does
In the polls demo from aio-libs/aiohttp-demos, aiohttpdemo_polls/main.py builds the app in init_app: config from settings.get_config, Jinja2, app.cleanup_ctx.append(pg_context), routes and an error middleware, then web.run_app(app, host=..., port=...) with every other argument left at its default, which in aiohttp 3.13.5 (the version requirements-dev.txt pins) means shutdown_timeout 60 and keepalive_timeout 75 seconds. db.py creates the engine with create_async_engine(DSN.format(**config['postgres'])) over asyncpg 0.32.0 and SQLAlchemy 2.0.54, with no connect_args and no pool settings, even though config/polls.yaml still carries minsize and maxsize from the aiopg days and utils.py validates them in the trafaret schema. middlewares.py maps 404 and 500 to templates; views.py has four handlers, and vote opens a transaction with app[db_key].begin(). Tests in tests/ run against a real Postgres through config/polls_test.yaml, and .github/workflows/ci.yml starts Postgres and Redis as services and runs make test on Python 3.12.
There is no single timeout to turn on in aiohttp, so the agent adds three, each in the layer that owns it. A timeout_middleware in middlewares.py wraps each handler in asyncio.timeout(seconds) (Python 3.11 and newer, which CI already uses) and turns TimeoutError into web.HTTPServiceUnavailable, rendered by a new templates/503.html registered in the same overrides map as 404 and 500, with a Retry-After header. The database gets connect_args={'command_timeout': seconds} so asyncpg cancels a statement on the server, plus pool_size, max_overflow=0 and pool_timeout so a request waits a bounded time for a connection instead of forever; minsize and maxsize finally mean something, feeding the pool size. The server gets keepalive_timeout and shutdown_timeout passed to web.run_app from config.
All five numbers live in a new timeouts block in config/polls.yaml and config/polls_test.yaml, validated in utils.py by extending TRAFARET with a timeouts key, so a typo fails at startup the way a bad postgres block already does. The test config uses short values so tests do not wait. A streaming response or a future WebSocket route must not sit under the handler deadline, so the middleware skips handlers that carry a marker attribute, and the pull request shows the one-line way to opt a route out.
Tests go in tests/test_timeouts.py, in the same aiohttp_client style as tests/test_integration.py: a handler that sleeps past the configured deadline must return 503 with the new template, a handler that runs select pg_sleep(...) past command_timeout must surface as 503 rather than hang, and a plain GET / must still be 200. The agent installs Postgres in its sandbox with apt-get (the demo's README uses Docker for it, which the sandbox lacks), runs init_db.py to create the user and database as tests/conftest.py expects, then make flake and PYTHONASYNCIODEBUG=1 pytest tests as CI does, before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add request timeouts to this aiohttp app. Read aiohttpdemo_polls/main.py, db.py, middlewares.py, views.py, settings.py, utils.py, config/polls.yaml, config/polls_test.yaml, requirements-dev.txt, tests/conftest.py, tests/test_integration.py, Makefile and .github/workflows/ci.yml first. Add a timeouts block to both config files (request, statement, pool, keepalive, shutdown) and validate it in utils.py. Add a middleware in middlewares.py that wraps each handler in asyncio.timeout with the request value, answers a timeout with 503 and a Retry-After header rendered from a new templates/503.html, and skips handlers marked as streaming. In db.py pass command_timeout through connect_args and set pool_size from maxsize, max_overflow 0 and pool_timeout from config. Pass keepalive_timeout and shutdown_timeout to web.run_app in main.py. Add tests/test_timeouts.py covering a slow handler, a slow statement via pg_sleep, and a normal request. Install Postgres in the sandbox, run init_db.py, run make flake and PYTHONASYNCIODEBUG=1 pytest tests until they pass, then open a pull request that lists each timeout, its default and where it applies.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes aiohttpdemo_polls/main.py, db.py, middlewares.py and utils.py, adds templates/503.html and tests/test_timeouts.py, and updates both YAML files under config/. Its description is a table of the five timeouts with the layer each one lives in, the default the pull request chose and the config key that changes it, followed by the pytest and flake8 output from the sandbox.
It explains the ordering a reviewer will ask about: the handler deadline is longer than the statement timeout, so a slow query is reported as a database timeout with its own log line rather than as a generic handler timeout, and the shutdown timeout is longer than the handler deadline, so in-flight requests finish before the server stops.
Before merging, a reviewer sets production values for the deadline and the pool, decides which routes, if any, stream and need the marker, and checks that the proxy in front of the app has a read timeout at least as long as the handler deadline, which the description calls out.
Run it on every Linear issue labelled latency
An automation on the Project with a linear trigger on linear.issue.labeled, latency in config.labels, and the prompt 'this issue names a route or query that hangs or runs long; bound it with the timeouts block in config, add a test that reproduces the slow path, and open a pull request' starts one run per labelled issue once the middleware exists. The trigger adds the issue after the prompt and fills in nothing else, so an issue about a slow results page and an issue about a stuck connection pool each get a run that reads the code it names.
A team with several aiohttp services sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app: a service on aiopg gets the timeout in that driver's terms, and one that already runs under a process manager gets the shutdown timeout aligned with the manager's grace period.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Timeouts in an async app are a set of numbers that have to agree with each other: a handler deadline shorter than the statement timeout hides the real cause, a pool with no wait limit turns one slow query into a stalled process, and a shutdown timeout shorter than the deadline drops requests on deploy. The agent reads the driver, the pool and the server settings in this app and wires one config block through all three, then proves each path with a test against a real Postgres in its sandbox.
The test output and the diff stay with the run, so a reviewer sees the slow handler and the slow statement both answered with 503 rather than trusting the description. A team with several services runs the same request across all of them at once.
Frequently asked questions
Does asyncio.timeout cancel the database query?
It cancels the handler's task, and asyncpg handles that cancellation for a statement in flight. command_timeout is the second guard: it is enforced by the driver against the server whatever the handler does, so a query cannot outlive it even when the cancellation does not reach it in time.
Why 503 and not 504?
The app itself gave up, not an upstream it was waiting for. 503 with Retry-After tells a client and a load balancer that the request may succeed shortly; 504 is what the proxy in front of the app returns when the app does not answer at all, and the two should stay distinct in dashboards.
What about long-polling or WebSocket handlers?
They would be killed by a per-request deadline, so the middleware skips any handler marked with a streaming attribute, which the pull request shows on an example route. The keep-alive and shutdown timeouts still apply to them, and the shutdown path closes open sockets the way aiohttp's on_shutdown expects.
Does this need Python 3.11?
asyncio.timeout arrived in 3.11, and this project's CI runs 3.12. For a service pinned to 3.10 or older, the async-timeout package provides the same context manager, and the pull request names that substitution.