# Add Response Compression to a Litestar App

Yes. An agent turns on Litestar's built-in compression middleware with gzip or Brotli, proves it with a TestClient test on your CI matrix, and opens a PR.

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

## What the agent does

The agent starts by reading what the app already is. In a project laid out like litestar-org/litestar-hello-world, `app.py` is the whole application: two route handlers, `async_hello_world` on `/async` and `sync_hello_world` on `/sync` with `sync_to_thread=False`, both returning `{"hello": "world"}`, and `app = Litestar(route_handlers=[sync_hello_world, async_hello_world])` with no configuration objects at all. `pyproject.toml` depends on `litestar[standard]>=2.4.1`, `pdm.lock` pins Litestar 2.4.1, and the dev groups hold ruff with `select = ["ALL"]`, mypy in strict mode, pyright and pytest with `asyncio_mode = "auto"`. `tests/test_app.py` has two tests that open `TestClient(app=app)` and compare the JSON body. `.github/workflows/ci.yaml` runs pre-commit, then calls `test.yaml` for Python 3.8 through 3.11, where `pdm install` and `pdm run pytest` run, with coverage on 3.11 only.

Compression in Litestar is a configuration object, not a package. The agent imports `CompressionConfig` from `litestar.config.compression` and passes `compression_config=CompressionConfig(backend="gzip")` to the `Litestar` constructor. The gzip backend needs nothing beyond the standard library; the Brotli backend needs the `brotli` package, which Litestar ships as the extra `litestar[brotli]`, and keeps `brotli_gzip_fallback=True` so a client that sends only `Accept-Encoding: gzip` still gets a compressed body. The agent picks gzip for a project that lists `litestar[standard]` alone, and switches to Brotli only when the prompt asks for it, adding the extra to `pyproject.toml` and refreshing `pdm.lock` with `pdm lock` so the `pdm-lock-check` pre-commit hook keeps passing.

The detail that trips people up is `minimum_size`. Its default is 500 bytes, and the hello-world bodies are far smaller, so a naive test that asserts a `content-encoding` header on `/sync` fails even though the middleware is wired correctly. The agent adds a third handler, or reuses an existing one that returns a list, whose JSON body crosses the threshold, and writes the test against that: send `Accept-Encoding: gzip`, assert `response.headers["content-encoding"] == "gzip"`, and assert the decoded JSON is unchanged, which `TestClient` handles because it decodes the body for you. A second test sends no `Accept-Encoding` header and asserts the response is left alone. If the prompt sets `minimum_size` lower, the test documents why.

Before opening the pull request, the agent runs what CI runs: `pdm install`, `pdm run pytest`, and `pre-commit run --all-files`, which covers ruff, mypy, codespell and the lock check. Because ruff selects every rule, the new handler needs a docstring and a return annotation that matches the existing style (`Dict[str, Any]` with the `noqa: UP006` the file already uses), otherwise the lint step, not the test step, is what fails. The branch carries the `app.py` change, the new test, and the dependency change if Brotli was chosen, and nothing else.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add response compression to this Litestar app. Read app.py, pyproject.toml, pdm.lock, tests/test_app.py and the workflows under .github/workflows first. Pass a CompressionConfig from litestar.config.compression to the Litestar constructor with the gzip backend, keeping the default minimum_size of 500 bytes unless a comment in the code says otherwise. Add a test in tests/test_app.py that requests a response larger than minimum_size with Accept-Encoding: gzip and asserts the content-encoding header and an unchanged JSON body, and a second test that a request without Accept-Encoding is not compressed. Run pdm install, pdm run pytest and pre-commit run --all-files, fix anything they report, and open a pull request that quotes the test output and explains the minimum_size threshold.",
  "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 `app.py` (the import, the `compression_config` argument and, where needed, one handler that returns a body over the threshold) and `tests/test_app.py` (two new tests), plus `pyproject.toml` and `pdm.lock` only when Brotli was requested. Its description quotes the pytest and pre-commit output from the sandbox and states the `minimum_size` in effect, so a reviewer knows that small bodies pass through uncompressed by design rather than by mistake.

A reviewer checks three things: that the middleware is on the app rather than on one route, that the test asserts the header on a body that is actually large enough, and that the Python 3.8 leg of the matrix still passes, since `litestar[standard]` on 3.8 is the oldest combination the project supports. The CI workflow needs no change; the existing matrix exercises the new tests on every version.

After merge, any client that sends `Accept-Encoding` gets gzip bodies for responses over the threshold and identical bytes for the rest. Nothing about routing, status codes or the OpenAPI schema changes.

## Run it on every new Litestar service repository

A platform team that wants every Litestar service to compress by default keeps a list of repositories and starts one run per entry. A handler on the reader's own server sends this body to `POST /o/{org}/sessions` for each, naming the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried loop returns the run it already started instead of opening a second pull request. Each run reads its own `app.py` and finds the constructor, whether the app is one file or a package with an `asgi.py`.

For an existing fleet, an automation on each Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` can check that a change to the app constructor keeps the `compression_config` argument. An automation's run is read-only, so it posts a review comment when the argument disappears; the fix itself comes from a run started by hand or from the handler above.

## Why run it on Rush?

The work is small and the proof is what matters: the pull request shows the header assertion passing under the same `pdm run pytest` that CI runs, and the pre-commit output, including the strict mypy and ruff configuration this project carries, is kept with the run. A reviewer reads a diff and a log rather than reproducing the environment on a laptop.

Running the same change across several services at once gives each one its own sandbox, its own lockfile refresh and its own test output. A Brotli choice in one repository, where the extra and the lock change, does not leak into another that only needs gzip.

## Frequently asked questions

### Why does the hello-world response come back uncompressed?

Because `CompressionConfig` only compresses bodies at or above `minimum_size`, which defaults to 500 bytes, and `{"hello": "world"}` is far smaller. The agent tests against a body that crosses the threshold and says so in the pull request, so nobody mistakes the default for a bug.

### Gzip or Brotli?

Gzip needs no extra dependency and works with the `litestar[standard]` extra the project already has. Brotli needs `litestar[brotli]`, a change to `pyproject.toml` and `pdm.lock`, and keeps `brotli_gzip_fallback=True` so clients without Brotli support still get gzip. The agent uses gzip unless the prompt asks for Brotli.

### Will the strict linting in this project reject the change?

Ruff is configured with `select = ["ALL"]` and mypy with `strict = true`, so a new handler without a docstring or a return annotation fails pre-commit. The agent runs `pre-commit run --all-files` in the sandbox before pushing and matches the annotations the file already uses.

### Can one route opt out of compression?

Yes. `CompressionConfig` takes `exclude`, a path pattern or list of patterns the middleware skips, and `exclude_opt_key`, a route option key that disables it per handler. The agent only adds these when the prompt names a route that must stay uncompressed.

## More Litestar jobs

- [Add CORS to a Litestar API](https://getrush.ai/run/add-cors/litestar/)
- [Add Coverage to CI for a Litestar App](https://getrush.ai/run/add-coverage-to-ci/litestar/)
- [Add CSRF Protection to a Litestar App](https://getrush.ai/run/add-csrf-protection/litestar/)

## The same job on other stacks

- [Add Response Compression to an Actix Web App from a Linear Issue](https://getrush.ai/run/add-compression/actix/)
- [Add Response Compression to an Axum API](https://getrush.ai/run/add-compression/axum/)
- [Add Response Compression to an Echo App](https://getrush.ai/run/add-compression/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/)
