# Add Request Timeouts to an aiohttp App

Yes. An agent adds a handler deadline, database statement and pool timeouts, and server keep-alive and shutdown limits to an aiohttp app, configurable and tested.

[Run this on Rush](https://cloud.getrush.ai/run/add-request-timeouts/aiohttp/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

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

## More aiohttp jobs

- [Add Security Headers to an aiohttp App](https://getrush.ai/run/add-security-headers/aiohttp/)
- [Add Structured Logging to an aiohttp App](https://getrush.ai/run/add-structured-logging/aiohttp/)
- [Add WebSockets to an aiohttp App](https://getrush.ai/run/add-websockets/aiohttp/)

## The same job on other stacks

- [Add Request Timeouts to an Axios API Client](https://getrush.ai/run/add-request-timeouts/axios/)
- [Add Request Timeouts to an Axum API](https://getrush.ai/run/add-request-timeouts/axum/)
- [Add Request Timeouts to an Echo App](https://getrush.ai/run/add-request-timeouts/echo/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
