feat(debugger): instrument FastAPI route handlers via route-table patching (#780)

## Problem

Dynamic Instrumentation (DI) instruments a function by rebinding the
module-level name (`setattr(module, name, wrapper)`). That reaches
callers who look the function up by name at call time, but **not**
web-framework route handlers: when `@app.get(...)` runs at import time,
FastAPI captures a direct reference to the handler in its route table
(`APIRoute.endpoint`, and the dispatched `APIRoute.dependant.call`). The
module-level rebind never reaches those references, so requests routed
by FastAPI call the original unwrapped handler and **no snapshot is
produced**.

DI already solves this for Flask by patching `app.view_functions`, but
had no FastAPI equivalent.

## Fix

Add `_patch_fastapi_routes` / `_patch_single_fastapi_app`, dispatched
from the existing `_patch_framework_references` (so both install **and**
restore are symmetric — `restore_function` reuses the same path with
swapped args).

For each `APIRoute` whose handler matches the target (identity match
first, then a name+`__module__` fallback, mirroring the Flask
precedent), rebind **both** `route.endpoint` and `route.dependant.call`
(the attribute the dispatcher actually invokes). The already-built
`Dependant` stays valid because the DI wrapper preserves the handler
signature via `functools.wraps`, so no rebuild is needed. Per-route
errors are isolated so patching can never break the application
(SAFETY).

Works for both **sync** route handlers (run by FastAPI in a threadpool)
and **async** handlers (event loop) — DI's existing sync/async wrapper
selection composes with the route patch.

## Tests

- **Unit tests** (`test_function_wrapper_fastapi.py`) mirroring the
Flask coverage: identity match, name+module fallback, no-op when FastAPI
absent / no app / not-a-route, and integration via
`_replace_function_in_module` and `restore_function`.
- **New `di-fastapi` contract-test app + suite** mirroring the Flask DI
suite (function-level, probe, line-level, hit-limit, coexistence,
capture-limits) plus async-function tests and **sync + async
route-handler tests** that assert a snapshot is produced.
- Added `wait_for_method_snapshots(method_name, ...)` to the DI contract
base to wait for a specific method's snapshot (avoids a batch-flush race
where another function's snapshot arrives first).

## Verification

- Distro unit tests: 18/18 wrapper tests (9 FastAPI + 9 Flask) + 92
other wrapper tests pass; pylint 10.00/10; black clean.
- FastAPI DI contract suite: 29 passed.
- Flask DI contract suite (rebuilt on the patched wheel): 24 passed — no
regression on the shared dispatch path.

Author: srprash

.codespellrc

@@ -1,4 +1,4 @@
 [codespell]
 # skipping auto generated folders
 skip = ./.tox,./.mypy_cache,./target,*/LICENSE,./venv,*/sql_dialect_keywords.json,*/3rd.txt
-ignore-words-list = afterall,assertIn,crate,SEH
+ignore-words-list = afterall,assertIn,crate,SEH,dependant

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/debugger/_function_wrapper.py

@@ -796,6 +796,7 @@ def _patch_framework_references(module, original_func: Callable, new_func: Calla
 
         Currently supports:
         - Flask: patches app.view_functions entries that reference the original function
+        - FastAPI: patches APIRoute.endpoint / APIRoute.dependant.call on app.router.routes
 
         Args:
             module: The module object containing the function
@@ -805,6 +806,8 @@ def _patch_framework_references(module, original_func: Callable, new_func: Calla
         try:
             # Flask: patch view_functions on any Flask app instances in the module
             FunctionWrapper._patch_flask_view_functions(module, original_func, new_func)
+            # FastAPI: patch route table entries on any FastAPI app instances in the module
+            FunctionWrapper._patch_fastapi_routes(module, original_func, new_func)
         except Exception as exc:
             # Never let framework patching failures break instrumentation
             logger.debug("Framework reference patching encountered an error: %s", exc)
@@ -900,6 +903,131 @@ def _matches(vf):
                 view_functions[ep] = new_func
                 logger.debug("Patched Flask view_functions[%s] by name+module match", ep)
 
+    @staticmethod
+    def _patch_fastapi_routes(module, original_func: Callable, new_func: Callable) -> None:
+        """
+        Patch FastAPI route table entries that reference the original function.
+
+        FastAPI's @app.get()/@app.post() decorators capture a direct reference to the
+        route handler at import time, storing it on each APIRoute as ``endpoint`` and
+        (via the pre-built Dependant) ``dependant.call``. The per-request dispatch path
+        invokes ``dependant.call``. Replacing the module-level name via setattr does NOT
+        update these references, so FastAPI keeps calling the original unwrapped handler.
+        This method finds and patches those references on any FastAPI app in the module.
+
+        Args:
+            module: The module object that may contain FastAPI app instances
+            original_func: The original function to find in the route table
+            new_func: The new wrapper function to replace it with
+        """
+        try:
+            try:
+                from fastapi import FastAPI  # pylint: disable=import-outside-toplevel
+            except ImportError:
+                return  # FastAPI not installed, nothing to patch
+
+            func_name = getattr(original_func, "__name__", "unknown")
+            func_module = getattr(original_func, "__module__", None)
+
+            # Scan module attributes for FastAPI app instances
+            for attr_name in dir(module):
+                try:
+                    attr = getattr(module, attr_name, None)
+                    if attr is None or not isinstance(attr, FastAPI):
+                        continue
+                    FunctionWrapper._patch_single_fastapi_app(
+                        attr, attr_name, original_func, new_func, func_name, func_module
+                    )
+                except Exception as exc:
+                    logger.warning("Error checking module attribute '%s' for FastAPI app: %s", attr_name, exc)
+                    continue
+
+        except Exception as exc:
+            logger.warning("Error patching FastAPI routes: %s", exc)
+
+    @staticmethod
+    def _patch_single_fastapi_app(  # pylint: disable=too-many-locals
+        fastapi_app, app_name, original_func, new_func, func_name, func_module=None
+    ):
+        """Patch route handler references in a single FastAPI app instance.
+
+        Rebinds both ``route.endpoint`` and ``route.dependant.call`` (the attribute the
+        dispatcher actually invokes). The pre-built Dependant remains valid because the
+        DI wrapper preserves the handler signature via functools.wraps, so no rebuild is
+        needed. ``app.include_router`` flattens sub-routers into ``app.router.routes``,
+        so iterating that list covers all routes.
+        """
+        router = getattr(fastapi_app, "router", None)
+        routes = getattr(router, "routes", None)
+        if not isinstance(routes, list):
+            logger.debug("FastAPI app '%s' has no router.routes list", app_name)
+            return
+
+        def _rebind(route) -> None:
+            route.endpoint = new_func
+            dependant = getattr(route, "dependant", None)
+            if dependant is not None and hasattr(dependant, "call"):
+                dependant.call = new_func
+
+        def _is_identity_match(route) -> bool:
+            if getattr(route, "endpoint", None) is original_func:
+                return True
+            dependant = getattr(route, "dependant", None)
+            return dependant is not None and getattr(dependant, "call", None) is original_func
+
+        # Identity match first. Guard each route independently so one bad route
+        # cannot abort patching of the others.
+        patched_count = 0
+        for route in routes:
+            try:
+                if getattr(route, "endpoint", None) is None:
+                    continue  # not an APIRoute (e.g. Mount/WebSocketRoute)
+                if _is_identity_match(route):
+                    _rebind(route)
+                    patched_count += 1
+                    logger.debug("Patched FastAPI route '%s' to use DI wrapper", getattr(route, "path", "?"))
+            except Exception as exc:
+                logger.warning("Error patching FastAPI route '%s': %s", getattr(route, "path", "?"), exc)
+                continue
+
+        if patched_count > 0:
+            logger.debug(
+                "Patched %d FastAPI route(s) for function '%s' on app '%s'",
+                patched_count,
+                func_name,
+                app_name,
+            )
+            return
+
+        # Identity check failed -- try name+module-based matching. functools.wraps
+        # (used by DI's own wrapper and by OTel instrumentation) preserves __module__,
+        # so requiring both name and module avoids patching a same-named handler from a
+        # different module. If the original has no __module__, fall back to name-only.
+        def _matches(endpoint):
+            if getattr(endpoint, "__name__", None) != func_name:
+                return False
+            if func_module is None:
+                return True
+            return getattr(endpoint, "__module__", None) == func_module
+
+        matching_routes = [r for r in routes if getattr(r, "endpoint", None) is not None and _matches(r.endpoint)]
+        if matching_routes:
+            logger.debug(
+                "FastAPI app '%s' has %d route(s) with name '%s' (module '%s') but identity "
+                "mismatch. Patching by name+module.",
+                app_name,
+                len(matching_routes),
+                func_name,
+                func_module,
+            )
+            for route in matching_routes:
+                try:
+                    _rebind(route)
+                    logger.debug("Patched FastAPI route '%s' by name+module match", getattr(route, "path", "?"))
+                except Exception as exc:
+                    logger.warning("Error patching FastAPI route '%s': %s", getattr(route, "path", "?"), exc)
+                    continue
+
     @staticmethod
     def _get_qualified_name(original_func: Callable) -> str:
         """Return a stable qualified name for functions and methods."""