docs(release): notes for 3.1.0

Author: lesnik512

planning/releases/3.1.0.md

@@ -0,0 +1,69 @@
+# modern-di-aiohttp 3.1.0 — the request container stops leaking into the GC
+
+Every request used to leave a reference cycle behind. `di_middleware` binds the
+`Request` into the container's context and then stored the container back into
+that same request, so the container — and the request and every dependency
+resolved during it — could only be reclaimed by the garbage collector, never by
+reference counting.
+
+**No public API change.** `FromDI`, `fetch_di_container`,
+`fetch_request_container`, `inject`, `setup_di`, `aiohttp_request_provider` and
+`aiohttp_websocket_provider` keep their signatures and behavior.
+
+## Fix
+
+- **The request container is removed from the request when the handler
+  returns**, in a `finally` so it also runs when the handler raises. The
+  container was already bounded by the `async with` around it, so nothing may
+  read the entry after that block — the entry outliving the request was the bug.
+
+  Measured over 100 requests against a real server, GC disabled during the run:
+
+  | modern-di | this integration | cyclic objects per request |
+  |---|---|---|
+  | 3.1.1 | 3.0.0 | 21.9 |
+  | **3.1.1** | **3.1.0** | **0** |
+
+  Bare aiohttp with no DI produces 0, so all of them were ours.
+
+  There were two independent cycles and both had to go. The other one — every
+  `Container` storing itself in its own `_scope_map` — was fixed upstream in
+  [modern-di 3.1.1](https://github.com/modern-python/modern-di/releases/tag/3.1.1).
+  Neither fix alone moves the number, which is why this release requires it.
+
+## Packaging
+
+- **`modern-di` floor raised to `>=3.1.1,<4`** (from `>=3,<4`). Required, not
+  cosmetic: this release's regression test fails against modern-di 3.0.0, which
+  the old range permitted, so leaving the floor alone would claim support for a
+  version the suite does not pass on.
+
+## Feature
+
+- **A canonical `examples/app.py`** — a minimal runnable aiohttp app wiring
+  modern-di end to end, covered by a test so it cannot rot.
+
+## Downstream
+
+Upgrading pulls modern-di 3.1.1 or newer. No code change needed on your side;
+no API of this package moved.
+
+If you read `request[_CONTAINER_REQUEST_KEY]` directly rather than through
+`FromDI` / `fetch_request_container`, note that the entry is now gone once the
+handler returns. Reading it during the request is unchanged.
+
+## Why this was found
+
+An audit of all 12 modern-di integrations that build per-request containers,
+prompted by the upstream 3.1.1 fix. Two were affected: this one and
+`modern-di-starlette` (fixed in its 3.1.0). Both shared the same signature —
+the container stashed inside the very request object its own context points at.
+The other ten are clean: `fastapi`, `litestar` and `taskiq` expose the container
+through a yield dependency and never store it back; `flask`, `aiogram` and
+`faststream` store it somewhere the context cannot reach; `celery`, `arq` and
+`typer` pass no context at all; `grpc` keeps the child in a contextvar the
+`ServicerContext` cannot reach.
+
+## Internals
+
+- 12 tests, 100% line coverage, Python 3.10–3.14; `ruff`, `ty` clean.