From decorator to request lifecycle

Everything starts with a deceptively simple decorator:

router = APIRouter()

@router.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: str):
    return Item(id=item_id, name="example")

Behind that snippet is a routing pipeline built around fastapi/routing.py:

fastapi/
├── applications.py    # FastAPI app object
├── routing.py         # <== This file
│   ├── request_response()      (HTTP ASGI adapter)
│   ├── websocket_session()     (WebSocket ASGI adapter)
│   ├── APIRoute                (HTTP route adapter)
│   └── APIRouter               (High-level router)

Request flow:

[ASGI Server] -> [Starlette Router] -> [APIRoute.app ASGI]
    -> request_response()
        -> get_request_handler()
        -> solve_dependencies() -> endpoint() -> serialize_response()

If we know which layer owns which responsibility, we can extend, debug, or replace parts of the stack without treating FastAPI as opaque framework magic.

The ASGI interface is a callable that takes a scope, receive, and send and drives the HTTP exchange. Starlette provides a generic router that matches paths and methods. fastapi/routing.py specializes that router in three ways:

• Dependency injection via Dependant graphs and solve_dependencies() per request.
• Validation contracts that turn invalid inputs into RequestValidationError and invalid outputs into ResponseValidationError.
• Lifecycles using AsyncExitStack so per‑request and per‑dependency cleanup always runs, even on errors.

The routing adapter pattern in action

FastAPI doesn’t replace Starlette’s router; it adapts it with extra behavior. The core of that adaptation is request_response, which wraps a regular handler into an ASGI app while wiring in lifecycles and safety checks.

Wrapping handlers into ASGI apps

def request_response(
    func: Callable[[Request], Awaitable[Response] | Response],
) -> ASGIApp:
    f = func if is_async_callable(func) else functools.partial(run_in_threadpool, func)

    async def app(scope: Scope, receive: Receive, send: Send) -> None:
        request = Request(scope, receive, send)

        async def app(scope: Scope, receive: Receive, send: Send) -> None:
            response_awaited = False
            async with AsyncExitStack() as request_stack:
                scope["fastapi_inner_astack"] = request_stack
                async with AsyncExitStack() as function_stack:
                    scope["fastapi_function_astack"] = function_stack
                    response = await f(request)
                await response(scope, receive, send)
                response_awaited = True
            if not response_awaited:
                raise FastAPIError("Response not awaited ...")

        await wrap_app_handling_exceptions(app, request)(scope, receive, send)

    return app

The key moves:

• Sync/async unification: synchronous handlers are wrapped in run_in_threadpool so the event loop stays non‑blocking. This keeps the ASGI server responsive even when some endpoints are sync.
• Lifecycles via AsyncExitStack: two exit stacks are attached to the ASGI scope—one for dependency cleanup, one for function‑scoped resources—so anything declared with yield or context managers gets a reliable teardown.

APIRoute: compiling routes at startup

APIRoute sits between the user‑facing decorators and the ASGI app produced by request_response. It compiles route configuration once at startup so request handling can stay lean:

class APIRoute(routing.Route):
    def __init__(
        self,
        path: str,
        endpoint: Callable[..., Any],
        *,
        response_model: Any = Default(None),
        status_code: int | None = None,
        ...
    ) -> None:
        self.path = path
        self.endpoint = endpoint
        if isinstance(response_model, DefaultPlaceholder):
            return_annotation = get_typed_return_annotation(endpoint)
            if lenient_issubclass(return_annotation, Response):
                response_model = None
            else:
                response_model = return_annotation
        self.response_model = response_model
        ...
        if self.response_model:
            assert is_body_allowed_for_status_code(status_code), (
                f"Status code {status_code} must not have a response body"
            )
            response_name = "Response_" + self.unique_id
            self.response_field = create_model_field(
                name=response_name,
                type_=self.response_model,
                mode="serialization",
            )
        else:
            self.response_field = None
        ...
        self.dependant = get_dependant(
            path=self.path_format, call=self.endpoint, scope="function"
        )
        ...
        self.body_field = get_body_field(...)
        self.app = request_response(self.get_route_handler())

Three design patterns show up here:

• Automatic response models: if you don’t pass response_model, FastAPI inspects the endpoint’s return annotation. If it’s not a Response subclass, that type becomes the response model and drives serialization and docs.
• Fail fast on invalid combinations: is_body_allowed_for_status_code enforces rules like “204 must not have a body” at startup, not in production.
• Configuration vs execution separation: path compilation, dependency graph building, and response field creation all happen once. Per‑request work is delegated to get_request_handler, keeping the hot path focused.

At the next layer up, APIRouter provides the ergonomic API—get, post, delete, and friends—which are thin wrappers around add_api_route. Internally, the responsibilities line up like this:

Dependencies, lifecycles, and error contracts

The most critical logic in fastapi/routing.py lives inside get_request_handler, the per‑route engine that runs on every request. This is where request parsing, dependency resolution, endpoint execution, and response validation are tied together into a single, well‑defined contract.

One handler for the full lifecycle

get_request_handler returns a coroutine app(request) with five responsibilities:

1. Parse and normalize the request body.
2. Resolve dependencies into concrete values.
3. Call the endpoint, handling sync and async functions.
4. Validate and serialize the response.
5. Turn failures into structured exceptions that the rest of FastAPI can understand.

def get_request_handler(...):
    ...
    async def app(request: Request) -> Response:
        response: Response | None = None
        file_stack = request.scope.get("fastapi_middleware_astack")
        assert isinstance(file_stack, AsyncExitStack)

        endpoint_ctx = (
            _extract_endpoint_context(dependant.call)
            if dependant.call
            else EndpointContext()
        )
        if dependant.path:
            mount_path = request.scope.get("root_path", "").rstrip("/")
            endpoint_ctx["path"] = f"{request.method} {mount_path}{dependant.path}"

        # 1. Read body and auto-close files
        try:
            body: Any = None
            if body_field:
                if is_body_form:
                    body = await request.form()
                    file_stack.push_async_callback(body.close)
                else:
                    body_bytes = await request.body()
                    if body_bytes:
                        json_body: Any = Undefined
                        content_type_value = request.headers.get("content-type")
                        if not content_type_value:
                            json_body = await request.json()
                        else:
                            message = email.message.Message()
                            message["content-type"] = content_type_value
                            if message.get_content_maintype() == "application":
                                subtype = message.get_content_subtype()
                                if subtype == "json" or subtype.endswith("+json"):
                                    json_body = await request.json()
                        if json_body != Undefined:
                            body = json_body
                        else:
                            body = body_bytes
        except json.JSONDecodeError as e:
            ... raise RequestValidationError(..., endpoint_ctx=endpoint_ctx)
        except HTTPException:
            raise
        except Exception as e:
            raise HTTPException(status_code=400, detail="There was an error parsing the body") from e

        # 2. Solve dependencies
        async_exit_stack = request.scope.get("fastapi_inner_astack")
        assert isinstance(async_exit_stack, AsyncExitStack)
        solved_result = await solve_dependencies(...)

        if not solved_result.errors:
            # 3. Call endpoint & 4. serialize
            raw_response = await run_endpoint_function(...)
            ...
            content = await serialize_response(..., endpoint_ctx=endpoint_ctx, ...)
            ...
        if errors:
            raise RequestValidationError(errors, body=body, endpoint_ctx=endpoint_ctx)

        assert response
        return response

    return app

A few important choices stand out:

• Content‑type aware body parsing: instead of always calling request.json(), the handler inspects the Content-Type header using email.message.Message. Only when the media type is JSON (or +json) does it parse as JSON; otherwise it preserves raw bytes. That avoids “helpful” parsing that would mangle binary or non‑JSON payloads.
• Structured, contextual errors: when JSON is invalid, it raises RequestValidationError with a machine‑readable error (e.g. type="json_invalid", location, parser message) and an endpoint_ctx containing file, line number, function name, and HTTP path. That context flows through logs and error responses and is what makes large apps debuggable.
• Clear error contracts at the boundary:
  • Problems with request data → RequestValidationError.
  • Endpoint returning data that violates the response model → ResponseValidationError.
  • Intentional HTTP responses from user code → HTTPException.

Endpoint context: small helper, big impact

To populate endpoint_ctx, the module uses _extract_endpoint_context, backed by a cache:

_endpoint_context_cache: dict[int, EndpointContext] = {}


def _extract_endpoint_context(func: Any) -> EndpointContext:
    """Extract endpoint context with caching to avoid repeated file I/O."""
    func_id = id(func)

    if func_id in _endpoint_context_cache:
        return _endpoint_context_cache[func_id]

    try:
        ctx: EndpointContext = {}

        if (source_file := inspect.getsourcefile(func)) is not None:
            ctx["file"] = source_file
        if (line_number := inspect.getsourcelines(func)[1]) is not None:
            ctx["line"] = line_number
        if (func_name := getattr(func, "__name__", None)) is not None:
            ctx["function"] = func_name
    except Exception:
        ctx = EndpointContext()

    _endpoint_context_cache[func_id] = ctx
    return ctx

Two lessons to lift directly:

• Compute introspection once: reading source files and line numbers is expensive. Caching by id(func) pays this cost once per endpoint instead of per request or per error.
• Fail soft on observability: the try/except ensures that if introspection fails, request handling doesn’t. You might lose some context, but you don’t lose the endpoint.

The cache is intentionally unbounded. In typical FastAPI apps with a static set of endpoints, that’s effectively bounded by the number of routes. In more dynamic setups that register handlers at runtime, it can grow over time, which is why the report flags it as a potential slow memory leak.

Dependencies as a recipe engine

Although the dependency system is defined elsewhere, fastapi/routing.py shows how routing uses it:

• APIRoute builds a Dependant tree from the endpoint and declared dependencies.
• get_request_handler calls solve_dependencies with the request, parsed body, and an AsyncExitStack so dependency cleanups are registered.
• The resulting values dictionary feeds directly into run_endpoint_function.

Conceptually, each endpoint declares a recipe—“give me a database session, the current user, and this body model”. Dependant is the recipe; solve_dependencies is the cook that figures out order, evaluates dependencies, and hands the endpoint fully prepared arguments.

What changes at scale

The same design that keeps the API surface simple also has to hold up under high load. fastapi/routing.py concentrates complexity and performance‑sensitive logic in a few hot paths.

Hot paths and complexity budget

The main hot paths are:

• The per‑request handler produced by get_request_handler.
• Dependency resolution via solve_dependencies and run_endpoint_function.
• Response serialization via serialize_response.

get_request_handler has a cyclomatic complexity of 18 and cognitive complexity of 20—high, but deliberately centralized. One complex, well‑tested engine is easier to reason about and optimize than dozens of ad‑hoc handlers spread across user code.

Roughly speaking, per‑request time looks like O(b + d + r):

• b: size of the request body.
• d: number (and nesting) of dependencies.
• r: size and shape of the response model graph.

FastAPI mitigates r with a “fast path” in serialize_response: when using the default JSONResponse and a response field, it can serialize directly to JSON bytes via Pydantic’s Rust core (dump_json), avoiding extra intermediate structures. That’s optimization placed exactly where it pays off: next to a well‑defined abstraction boundary.

Observability hooks worth copying

The report proposes metrics that map directly to the responsibilities we’ve seen. They double as a design checklist for your own services:

• fastapi_request_handler_duration_seconds: total time in the routing/handler layer. Tells you if the framework glue is the bottleneck.
• fastapi_dependency_resolution_duration_seconds: isolates time spent in solve_dependencies. Useful for diagnosing endpoints that look simple but have heavy dependency graphs.
• fastapi_response_serialization_duration_seconds: measures the cost of turning Python objects into wire JSON.
• fastapi_sync_endpoint_threadpool_queue_length: surfaces threadpool saturation when many sync handlers are in play.
• fastapi_endpoint_context_cache_size: tracks growth of the endpoint context cache.

Even if you’re not using FastAPI, the pattern is reusable: measure parsing, dependency wiring, and serialization separately from business logic, so you know which layer to optimize.

Safety vs ergonomics

This module also illustrates a few trade‑offs common in framework design:

• Assertions vs explicit errors: get_request_handler asserts that fastapi_inner_astack and fastapi_middleware_astack exist in the ASGI scope. In misconfigured deployments this surfaces as a raw AssertionError. A more user‑friendly choice would be a FastAPIError with guidance, which the report recommends.
• Large module vs conceptual coherence: fastapi/routing.py includes low‑level helpers, route classes, router logic, and all HTTP verb decorators. The public API stays clean, but the file becomes harder to navigate. Splitting it into smaller modules (routing_base.py, routes.py, router.py) would keep responsibilities aligned while reducing contributor cognitive load.
• Decorator duplication for HTTP verbs: get, post, put, etc. largely repeat the same logic. That duplication buys per‑verb docstrings but complicates maintenance. An internal helper like _method_route() that all verbs delegate to would preserve DX while centralizing behavior.

Applying these ideas in your code

The constant theme across fastapi/routing.py is disciplined layering: a simple decorator‑based surface backed by adapters, lifecycle management, and strong contracts. You can apply the same approach in your own services and internal frameworks.

1. Separate declaration, configuration, and execution

• Declaration: user code (@router.get("/items")) should state intent in the smallest API you can design.
• Configuration: compile as much as possible up front—paths, dependency graphs, response models—just like APIRoute.__init__ does.
• Execution: keep the per‑request engine focused on the lifecycle: parse → resolve dependencies → call handler → serialize → emit errors.

You can reuse this pattern for job runners, event processors, or internal RPC layers: decorators to declare work, a compilation step that builds a route/recipe object, and a compact execution engine.

2. Design explicit error contracts at boundaries

Whenever you cross a boundary—HTTP, queues, or external APIs—treat it like FastAPI treats HTTP:

• Validate inputs and raise a dedicated “request” error type.
• Validate outputs against a contract and raise a distinct “response” error type when you break your own promises.
• Attach rich context (file, function, operation name) to every such error.

This makes it obvious whether a bug is in the caller, the callee, or the boundary glue—exactly what you want at scale.

3. Add tiny helpers that improve debuggability

Utilities like _extract_endpoint_context and the “response not awaited” check in request_response are small in code size but large in operational value. They turn vague failures into specific, actionable messages.

In your own systems, ask: “When this fails at 2 a.m., what context will I wish I had?” Then bake that into small, always‑on helpers on the hot path.

4. Plan for lifecycle and scale early

Patterns from fastapi/routing.py that are worth adopting even in small projects:

• Unify sync and async behavior behind an explicit boundary (e.g. a threadpool adapter).
• Use a structured lifecycle mechanism (AsyncExitStack or equivalent) instead of ad‑hoc try/finally blocks sprinkled everywhere.
• Measure parsing, dependency resolution, and serialization separately so you can scale the right part later.

FastAPI’s routing layer is more than a set of decorators; it’s a carefully layered adapter between ordinary Python functions and the concurrent, failure‑prone world of HTTP and WebSockets. By studying how fastapi/routing.py isolates responsibilities, enforces contracts, and surfaces rich errors, we get a concrete blueprint for turning simple code into production‑grade infrastructure.

As you evolve your own services or internal frameworks, keep asking: how can my “router” be as focused, observable, and user‑friendly as this one—while still hiding as much incidental complexity as possible from the people who just want to write business logic?