Starlette source notes

Repo: encode/starlette Local checkout: /home/ubuntu/repos/rodin-sources/starlette

Why this repo was chosen

FastAPI inherits key runtime behavior from Starlette. Starlette is the right source for conventions around app assembly, middleware ordering, lifespan, and request state.
Valuable here because it distinguishes framework guarantees from habits that only appear in sample apps.

starlette/applications.py:22-55 defines the constructor with distinct parameters for routes, middleware, exception handlers, and lifespan.
tests/test_applications.py:139-157 builds one app by explicitly passing routes, exception handlers, middleware, and lifespan together.

Why chosen:

This separation exists both in the public constructor and in the main integration-style test app.

Implication for synthesis:

Treat app assembly concerns as separate layers; do not blur middleware, routing, error handling, and startup resources into one module-level setup blob.

starlette/applications.py:35-40 documents that ServerErrorMiddleware is outermost and ExceptionMiddleware innermost.
starlette/applications.py:68-77 shows the actual stack construction: framework error middleware, then user middleware, then framework exception middleware around the router.
starlette/applications.py:98-101 forbids adding middleware after the application has started.

Why chosen:

This is stronger than a docs recommendation; it is constructor/runtime behavior.

Caveat / counterexample:

User middleware is not the whole stack. If a synthesized convention says "middleware runs in the order you add it," that is incomplete because Starlette wraps user middleware with framework-owned layers.

Implication for synthesis:

When discussing middleware order, mention Starlette's outer/inner framework layers explicitly.
Avoid recommendations that rely on mutating middleware after startup.

starlette/applications.py:46-48 says lifespan replaces on_startup/on_shutdown; use one style or the other, not both.
tests/test_applications.py:394-409 shows the preferred shape: an @asynccontextmanager lifespan marks startup before yield and cleanup after yield, with both verified by entering/exiting the client context.
tests/test_applications.py:108-114 defines lifespan state by yielding {"count": 1}.
tests/test_applications.py:241-244 verifies request handlers can consume that state via request.state.

Why chosen:

This combines constructor guidance with working tests for startup/cleanup and state propagation.

Caveat / counterexample:

tests/test_applications.py:421-459 still supports async/sync generator lifespan forms, but those tests are under a deprecation-warning filter. For future-facing synthesis, prefer @asynccontextmanager, not raw generator lifespans.

Implication for synthesis:

Recommend lifespan for DB pools, clients, caches, and other app resources.
Note that lifespan can yield structured state for handlers instead of relying on import-time globals.

Constructor-level separation of app assembly concerns: starlette/applications.py:22-55
Middleware stack ordering is framework-defined: starlette/applications.py:68-77
Cannot add middleware after startup: starlette/applications.py:98-101
Lifespan replaces startup/shutdown hooks: starlette/applications.py:46-48
Preferred @asynccontextmanager lifespan behavior: tests/test_applications.py:394-409

separate routes, middleware, exception handlers, and lifespan at app assembly time
preserve middleware ordering intentionally, including framework-owned outer/inner layers
prefer lifespan over startup/shutdown hooks for resource management
use lifespan-yielded state instead of import-time globals for app-scoped data