F25.1 — Typed application state
| State | Closed |
| Parent | E25 |
| Iteration | Release 10 |
| Start Date | 2026-11-18 |
| Closed Date | 2026-11-18 |
| Predecessors | — |
| Source | Owner request, 2026-10-21; promoted 2026-11-18 |
Stories: 2 Closed
| Story | State | Depends on |
|---|---|---|
| S25.1.1 — Settle the typed-state API | Closed (2026-11-18) | — |
| S25.1.2 — Build typed application state | Closed (2026-11-18) | S25.1.1 |
rn-forge-fastapi declares an application's state once, with its attributes and
types, and a route receives it through Depends, so a misspelt or missing
resource fails type checking instead of at request time.
Context
A FastAPI application that keeps long-lived resources on app.state reads them
back as request.app.state.<name>, which is untyped: Apollo does so 195 times.
Apollo is the motivation, not a gate: every acceptance line here is checked inside pykit (ADR-0008).
S25.1.1 — Settle the typed-state API
State: Closed (2026-11-18)
Acceptance:
- The story records one settled contract covering declaration, route access
through
Depends, how a misspelt or mistyped attribute fails undertask typecheck, a resource absent at startup, and thelifespaninteraction. - The contract names the public symbols and their module, and states whether any existing public API changes.
- Options considered and rejected are listed with one line each.
Settled contract (owner, 2026-11-18):
- Declaration. The application defines a class, by convention a frozen
dataclass(slots=True, kw_only=True), whose attributes are its resources with their types. An application may declare several state classes;app_statekeys them by class. - Opening. An async context manager
opener(app) -> AbstractAsyncContextManager[S]builds the state and releases it on shutdown.state_lifespan(S, opener, inner=None)returns aLifespan[FastAPI]passed aslifespan=toFastApiApporFastAPI. Setup runs the opener, theninner; teardown runs in reverse. - Route access.
app_state(S)returns a dependency, so routes takestate: Annotated[S, Depends(app_state(S))], usually through an application alias. The factory is cached per class, soapp.dependency_overrides[app_state(S)]replaces the state in tests. - Type errors. A misspelt or mistyped attribute is a pyright strict error
(
reportAttributeAccessIssue,reportReturnType). No permanent test proves it: the error comes from pyright's generics, so such a test would check pyright, not this package. - Absent at startup. A missing field fails in the application's own
constructor call. An opener that yields something other than an
Sinstance raisesTypeError("<S> expected, got <T>")before the application serves. - Absent at request time.
app_state(S)on an application whose lifespan never registeredSraisesRuntimeError("no <S> registered on this application"), a 500. - Public symbols.
app_stateandstate_lifespan, in a new modulern_forge/fastapi/state.py, exported fromrn_forge.fastapi. No existing public API changes. - Rejected. Starlette lifespan state typed as a
TypedDict: the read needs an uncheckedcastand nothing is checked at startup. One dependency per resource:app.state.<name>stays untyped inside each dependency. A genericFastApiApp[S]:request.appis typedFastAPI, so a route cannot recoverSwithout a cast.FastApiApp(state=(S, opener)): it changes an existing API for no gain overstate_lifespan.
Outcome: with a misspelling and a wrong return type added to a prototype
under src/, task typecheck reported reportAttributeAccessIssue and
reportReturnType; a route reading request.app.state.dbb passes pyright
strict and fails with a 500.
S25.1.2 — Build typed application state
State: Closed (2026-11-18) · Depends on: S25.1.1
Acceptance:
- A test application declares its state with the settled API and a route reads
an attribute through
Depends; the request succeeds and the value is the one set at startup. - An application with a declared resource absent fails at startup in the way S25.1.1 settled; a test asserts the exception and its message.
- A route on an application whose lifespan never registered the state fails as S25.1.1 settled; a test asserts the exception and its message.
- A test replaces the state through
app.dependency_overrides. - The state's setup and teardown run with the application's
lifespan, as S25.1.1 settled; a test asserts the order. - The package's guide describes the API, and the package's
CHANGELOG.mdhas an entry under[Unreleased]. - The new symbols are exported from
rn_forge.fastapi, andtask validatepasses.