Skip to content

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 under task typecheck, a resource absent at startup, and the lifespan interaction.
  • 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_state keys 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 a Lifespan[FastAPI] passed as lifespan= to FastApiApp or FastAPI. Setup runs the opener, then inner; teardown runs in reverse.
  • Route access. app_state(S) returns a dependency, so routes take state: Annotated[S, Depends(app_state(S))], usually through an application alias. The factory is cached per class, so app.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 S instance raises TypeError("<S> expected, got <T>") before the application serves.
  • Absent at request time. app_state(S) on an application whose lifespan never registered S raises RuntimeError("no <S> registered on this application"), a 500.
  • Public symbols. app_state and state_lifespan, in a new module rn_forge/fastapi/state.py, exported from rn_forge.fastapi. No existing public API changes.
  • Rejected. Starlette lifespan state typed as a TypedDict: the read needs an unchecked cast and nothing is checked at startup. One dependency per resource: app.state.<name> stays untyped inside each dependency. A generic FastApiApp[S]: request.app is typed FastAPI, so a route cannot recover S without a cast. FastApiApp(state=(S, opener)): it changes an existing API for no gain over state_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.md has an entry under [Unreleased].
  • The new symbols are exported from rn_forge.fastapi, and task validate passes.

Acceptance

set -euo pipefail
task validate   # S25.1.1, S25.1.2