loom.rest.fastapi.router_runtime

Router runtime — binds CompiledRoute records to a FastAPI application.

Generates async handler functions at startup, one per CompiledRoute. Each handler:

  1. Extracts path parameters from request.path_params (populated by Starlette’s routing layer from the URL).

  2. Reads the raw request body and decodes it with msgspec.json.decode when bytes are present.

  3. Builds the UseCase instance via the UseCaseFactory.

  4. Drives execution through RuntimeExecutor.

  5. Returns a MsgspecJSONResponse.

Handler __signature__ is manipulated so FastAPI validates and documents path parameters correctly in OpenAPI while keeping the implementation generic.

No reflection occurs at request time — all structural decisions (path params, status codes, tags) are taken from the CompiledRoute produced at startup.

Functions

_build_query_spec(request, *, ...)

_camel_to_snake(value)

_coerce_scalar(value)

_extract_path_params(path)

Return ordered path-parameter names from a FastAPI path template.

_make_handler(compiled_route, factory, executor)

Build an async handler for the given compiled route.

_normalize_field_name(value)

_normalize_path_param_annotation(annotation)

_parse_filter_op(op)

_parse_filter_specs(query_params)

_parse_pagination_mode(raw, cursor, *, ...)

_parse_sort(sort_field, direction_raw)

_resolve_query_param_name(uc_type)

_route_docs(compiled_route)

Resolve OpenAPI summary/description from route metadata or UseCase docs.

bind_interfaces(app, compiled_routes, ...)

Register compiled routes on a FastAPI application.
loom.rest.fastapi.router_runtime.bind_interfaces(app, compiled_routes, factory, executor)[source]

Register compiled routes on a FastAPI application.

For each CompiledRoute, creates a dynamic async handler and registers it via app.add_api_route. Path parameters are inferred from the route path template and exposed in the handler signature so FastAPI validates and documents them correctly.

Nested JSON Schema $defs produced by msgspec/pydantic are collected into a shared component registry and returned. The caller is responsible for injecting these into components.schemas of the OpenAPI document.

Parameters:

  • app (fastapi.FastAPI) – FastAPI application instance to register routes on.

  • compiled_routes (Sequence[CompiledRoute]) – Ordered list of fully resolved routes produced by RestInterfaceCompiler.

  • factory (UseCaseFactory) – Use-case factory for constructing instances per request.

  • executor (RuntimeExecutor) – Runtime executor that drives the use-case pipeline.

Returns:

Mapping of schema name → JSON Schema fragment for all collected $defs that should appear under components.schemas.

Return type:

dict[str, Any]

Example:

compiler = RestInterfaceCompiler(use_case_compiler)
routes = compiler.compile(UserRestInterface)
component_schemas = bind_interfaces(app, routes, factory, executor)