Should we rework architecture to support Dependency Injection?

[alukach]

I'm working on adding a feature to our stac-fastapi+pgstac catalog and have been experimenting with customizing the Transactions extension. I quickly found that the current stac-fastapi architecture does not support FastAPI's Dependency Injection (DI) feature. I figured that I would start this discussion to track the following:

1. Get an agreed-upon understanding of how/why we don't support DI
2. Get a consensus on whether it would make sense to modify the current stac-fastapi architecture so that it supports DI
3. Field some ideas on how we could support DI

DI in FastAPI

Why

I think FastAPI's use of DI is its killer feature. It provides an inversion of control wherein our controllers/route-handlers can declare their required input parameters and FastAPI will accommodate. This encourages developers to encapsulate common needs (eg auth requirements, obtaining db connections) into reusable dependencies and thereby cluttering their controller logic with these utility steps. Additionally, it makes testing controllers very simple as FastAPI ships with first-class support for overriding dependencies.

How it works

A quick exploration into FastAPI's code shows how they are doing the DI magic:

1. When we add a callable endpoint (ie controller) to a router via router.add_api_route(...), we create an APIRoute object.
2. On initialization of the APIRoute, we create a Dependant object of our controller.
3. Creating a dependant involves using the inspect module to retrieve the signature of the controller. It then iterates through each input parameter and if those are instances of the Depends class, turns those into Dependant objects (this involves some recursion where we do the same for each dependency's dependencies via get_param_sub_dependant(...) -> get_sub_depndant(...) -> get_dependant(...) -> get_param_sub_dependant(...) and so on).
4. The final step of creating a route is to add an app property onto the route instance. This is done by first creating a callable request handler which takes in a request, resolves the dependencies of the controller, calls the controller, and finally marshall's the response to the expected response class (link). That callable request handler is then converted into ASGIApp instance via Starlette's request_response(...).

After all of this, FastAPI has a router with individual ASGIApp route handlers to process requests. (☝️ was all of this necessary for this discussion? maybe not, but understanding this helped me figure out how DI could fit in with stac-fastapi and I wanted to log it somewhere 😅)

Dependency Injection in STAC FastAPI

Why doesn't it work?

Prior to adding any controller to our router, we first pass it through create_async_endpoint(...):

stac-fastapi/stac_fastapi/api/stac_fastapi/api/app.py

Lines 125 to 127 in 7ba0a40

	endpoint=create_async_endpoint(
	self.client.landing_page, EmptyRequest, self.response_class
	),

This seems to have three functions:

1. Converting non-coroutine controllers to coroutines:

   stac-fastapi/stac_fastapi/api/stac_fastapi/api/routes.py

   Lines 46 to 47 in 7ba0a40

   	if not inspect.iscoroutinefunction(func):
   	func = sync_to_async(func)

2. Wrapping the controller in our own controller which expects only the raw request object and the request object converted into an expected request model:

   stac-fastapi/stac_fastapi/api/stac_fastapi/api/routes.py

   Lines 73 to 82 in 7ba0a40

   	async def _endpoint(
   	request: Request,
   	request_data: Dict[str, Any], # type:ignore
   	):
   	"""Endpoint."""
   	return _wrap_response(
   	await func(request_data, request=request), response_class
   	)
   	return _endpoint

3. Marshalling the response of the called controller into our expected response model:

   stac-fastapi/stac_fastapi/api/stac_fastapi/api/routes.py

   Lines 56 to 58 in 7ba0a40

   	return _wrap_response(
   	await func(request=request, **request_data.kwargs()), response_class
   	)

Step 2 is where DI really falls down, as FastAPI's use of the inspect module now no longer sees the controller that we generate, rather it sees the wrapped controller that expects only the request and request coerced into our request model.

How to support Dependency Injection

Support for DI is pretty simple: stop using create_async_endpoint(...). FastAPI has its own mechanisms to handle non-coroutine controllers (our step 1) and coerce the response into our expected response class (step 3). It seems like the only possibly challenging part is converting a request object into an expected request model (step 2).

Normally within FastAPI, you would declare the request model as a dependency on the controller itself. However, I assume stac-fastapi wants to do this outside of the controller as we want to limit controller's abilities to dictate the request bodies as those come from the STAC Spec (ie we are enforcing that extensions comply with the STAC Spec). It seems like this is the hard part about supporting DI within stac-fastapi.

Ideas for enforcing the expected request model while supporting Dependency Injection

I haven't thought too deeply about this (and this is what I'd like to sort out in this discussion), but it feels like there is likely a path forward to get both top-down enforcement of the shape of the request and response objects for each controller within our extensions (ie enforcing the STAC Spec) while also granting controllers the inversion of control offered by DI.

One quick idea would be to make use route_class_override parameter of router.add_api_route(...). We could make our our APIRoute class that descends from FastAPI's APIRoute but also uses the inspect module to review the controller and ensure that it expects our specified request model and returns our expected response model, throwing an error otherwise.

---

I'd love to hear others' thoughts. Am I missing something regarding the purpose of create_async_endpoint(...)? Any obvious paths forward to supporting DI within the project?

[moradology]

This is an excellent writeup and I feel like I need some time to chew on this to get my thoughts clear but (at the risk of sounding a bit naive) I wonder whether we can't build out Depends objects more carefully here: https://github.com/stac-utils/stac-fastapi/blob/master/stac_fastapi/api/stac_fastapi/api/routes.py#L53 to enable FastAPI to construct Dependable instances as it normally would.
What am I missing? Not a rhetorical question: I feel like I'm not fully grasping the problem at the moment

[alukach]

I feel like I'm not fully grasping the problem at the moment

I'm somewhat in the same boat here, hence the overly-verbose breakdown of everything. I'm not 100% confident on my read of the codebase, so I'm just dumping how I think it's all working.

Let's go through that same exercise with the code that you're referencing:

stac-fastapi/stac_fastapi/api/stac_fastapi/api/routes.py

Lines 49 to 58 in 1de7b8b

	if issubclass(request_model, APIRequest):
	async def _endpoint(
	request: Request,
	request_data: request_model = Depends(), # type:ignore
	):
	"""Endpoint."""
	return _wrap_response(
	await func(request=request, **request_data.kwargs()), response_class
	)

In create_async_endpoint(...), we're dynamically creating a controller that expects a request object (FastAPI knows to inject the object when it sees a parameter typed with Request) and some request_data object of type request_model (this takes advantage of FastAPI's ability to accept Classes as Dependencies).

So how would we build this out to support flexible DI that enables an inversion of control?

• Extension Clients: In a situation where I'm building out something like a custom TransactionsClient (like the pgSTAC client), this wouldn't work because the request_model is declared top-down in the TransactionsExtension:

  stac-fastapi/stac_fastapi/extensions/stac_fastapi/extensions/core/transaction.py

  Lines 62 to 73 in 7ba0a40

  	def register_create_item(self):
  	"""Register create item endpoint (POST /collections/{collection_id}/items)."""
  	self.router.add_api_route(
  	name="Create Item",
  	path="/collections/{collection_id}/items",
  	response_model=Item if self.settings.enable_response_models else None,
  	response_class=self.response_class,
  	response_model_exclude_unset=True,
  	response_model_exclude_none=True,
  	methods=["POST"],
  	endpoint=create_async_endpoint(self.client.create_item, PostItem),
  	)

• Extensions: Okay, but how about we're building our own extension and thus could specify our own request_data object? I suppose we could rework the logic in create_async_endpoint(...) to support a request_data object that somehow indicates that it handles Depends() instances, although I'm not sure how we would do that. Also, this feels a bit awkward to me, as I would think that most developers who were familiar with FastAPI (but not stac-fastapi) would expect to declare dependencies within the controllers.

[geospatial-jeff]

Get an agreed-upon understanding of how/why we don't support DI

I don't think there was ever an intent to not support DI. It's really nice for all the reasons you describe and should be supported.

Get a consensus on whether it would make sense to modify the current stac-fastapi architecture so that it supports DI

This sounds like a good idea to me.

Support for DI is pretty simple: stop using create_async_endpoint(...). FastAPI has its own mechanisms to handle non-coroutine controllers (our step 1) and coerce the response into our expected response class (step 3). It seems like the only possibly challenging part is converting a request object into an expected request model (step 2).

FastAPI does support non-coroutine controllers, the function converts non-coroutine controllers into coroutines by running them in a threadpool because this makes the code simpler; the controller it creates isn't conditionally async def or def. FastAPI also runs non-coroutine controllers in a threadpool, so from a performance perspective it's identical.

FastAPI does let you use response_model to coerce the response into a certain response model. We discovered this could be VERY slow for some requests and disabled response models by default (settings.enable_response_models). Performance is important to a lot of people who use the project so I don't think we can rely on response_model here.

I agree with you that the create_async_endpoint function could just be removed.

Ideas for enforcing the expected request model while supporting Dependency Injection

One of the challenges is request model validation is different for POST vs. GET requests. POST requests are using a pydantic model declared as a type hint of the controller. While GET requests are using a dataclass as the type hint with a default value of Depends(). When this was written you couldn't use a pydantic model to validate query or path parameters, just a POST body (maybe this has changed?). Standardizing on a single way of request validation will help. A few ideas assuming we can do this:

• Use a generic type to build controllers with specific request validation (ex. post_search_controller = generic_controller[PostSearch]).
• Use functools.partial to partially initialize the function with specific defaults (ex. functools.partial(generic_controller[PostSearch], request_model=Depends())). A user could call this controller and pass their own dependencies as keyword arguments.

Another challenge is the business logic defined by the backend client may need to be aware of this dependency. I'm imagining something like an oauth dependency that validates a user's request based on an API key and returns a list of collections that user is allowed to search. In order to add a dependency, the user will have to:

1. Add the dependency to one of the endpoints.
2. Know which method on the backend client is being called by that endpoint.
3. Subclass that client, update the method on the backend client to accept the dependency.
4. Do something with the dependency.

Users who are adding dependencies are probably extending stac-fastapi internals anyways so maybe this isn't a big deal? One solution is to require dependencies to pass data to the backend through the Request object. Request can be injected into any dependency, and Request.state can be used to store state (ex. Request.state.allowed_collections). Request is also already injected into the backend methods (its needed for link generation). This still requires the user to modify the backend client method, but the method signature doesn't change which seems nice.