Starlette server fails with top level async-await

[C-Loftus]

Description

When launching pygeoapi with pygeoapi serve --starlette pygeoapi throws an error if you try to use top level async functions.
I expected to be able to use async functions without needing to use asyncio.run since the web server should initialize the async event loop.

If you are developing a large pygeoapi plugin with lots of fetch-based ETL, async is often needed and using asyncio.run over every async function adds a fair bit of boilerplate (and requires you to make sure another event loop isn't running / created by another plugin)

The error seems to signify that the content is not being awaited properly

Steps to Reproduce

1. Create a custom provider plugin
2. Create an async function like get inside the provider

    async def get(self, identifier, **kwargs):
        await asyncio.sleep(1)
    # rest of geojson response omitted here for brevity ...

3. When you call the oaf endpoint and thus call get() it will give the error:

Traceback (most recent call last):
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/uvicorn/protocols/http/h11_impl.py", line 403, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/uvicorn/middleware/proxy_headers.py", line 60, in __call__
    return await self.app(scope, receive, send)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/errors.py", line 187, in __call__
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/errors.py", line 165, in __call__
    await self.app(scope, receive, _send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/exceptions.py", line 62, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 460, in handle
    await self.app(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 288, in handle
    await self.app(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 76, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 73, in app
    response = await f(request)
               ^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 360, in collection_items
    return await execute_from_starlette(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 133, in execute_from_starlette
    headers, status, content = await loop.run_in_executor(
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/lib/python3.12/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 104, in call_api_threadsafe
    return api_call(*args)
           ^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/api/itemtypes.py", line 856, in get_collection_item
    if 'links' not in content:
       ^^^^^^^^^^^^^^^^^^^^^^
TypeError: argument of type 'coroutine' is not iterable

Expected behavior

I expect to be able to have starlette itself initialize the async event loop. I expected to be able to use async functions as it mentions in the starlette docs

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route


async def homepage(request):
    return JSONResponse({'hello': 'world'})


app = Starlette(debug=True, routes=[
    Route('/', homepage),
])

Environment

• OS: Macos Sonoma 14.3
• Python version: 3.12.8
• pygeoapi version: pygeoapi, version 0.20.dev0

[C-Loftus]

A similar issue is generated if you try to use the EDR provider instead of the OAF provider for a plugin. It appears in both cases a coroutine is not being awaited properly

    @BaseEDRProvider.register()
    async def area(
        self,
        wkt: str,
        select_properties: list[str] = [],
        datetime_: Optional[str] = None,
        z: Optional[str] = None,
        format_: Optional[str] = None,
        **kwargs,
    ):
        await asyncio.sleep(1)
        # .... rest of valid covjson response omitted here for brevity; but it doesn't get beyond the sleep regardless

Traceback (most recent call last):
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/uvicorn/protocols/http/h11_impl.py", line 403, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/uvicorn/middleware/proxy_headers.py", line 60, in __call__
    return await self.app(scope, receive, send)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/errors.py", line 187, in __call__
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/errors.py", line 165, in __call__
    await self.app(scope, receive, _send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/middleware/exceptions.py", line 62, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 460, in handle
    await self.app(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 288, in handle
    await self.app(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 76, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/starlette/routing.py", line 73, in app
    response = await f(request)
               ^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 506, in get_collection_edr_query
    return await execute_from_starlette(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 133, in execute_from_starlette
    headers, status, content = await loop.run_in_executor(
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/lib/python3.12/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/starlette_app.py", line 104, in call_api_threadsafe
    return api_call(*args)
           ^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/api/environmental_data_retrieval.py", line 420, in get_collection_edr_query
    content = to_json(data, api.pretty_print)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/util.py", line 284, in to_json
    return json.dumps(dict_, default=json_serial, indent=indent,
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cloftus/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/lib/python3.12/json/__init__.py", line 238, in dumps
    **kw).encode(obj)
          ^^^^^^^^^^^
  File "/Users/cloftus/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/lib/python3.12/json/encoder.py", line 202, in encode
    chunks = list(chunks)
             ^^^^^^^^^^^^
  File "/Users/cloftus/.local/share/uv/python/cpython-3.12.8-macos-aarch64-none/lib/python3.12/json/encoder.py", line 439, in _iterencode
    o = _default(o)
        ^^^^^^^^^^^
  File "/Users/cloftus/github/RISE-EDR/.venv/lib/python3.12/site-packages/pygeoapi/util.py", line 417, in json_serial
    raise TypeError(msg)
TypeError: <coroutine object RiseEDRProvider.area at 0x10f5d1f30> type <class 'coroutine'> not serializable

[webb-ben]

@francbartoli @ricardogsilva interested to hear you experience developing async within pygeoapi

[mikemahoney218-usgs]

I believe we're running into the same issue with our deployment! We've been trying to use starlette to help scale our server, but haven't had a ton of luck getting core pygeoapi to work well with an async postgres provider.

[francbartoli]

@mikemahoney218-usgs I can confirm that the core and the underlying providers - postgres included - don't support async/await at all.
As explained at the top of this issue by @C-Loftus even with a fully qualified async/await plugin built from scratch the core wouldn't be able to support the event loop.
the core will need to be refactored with an improved design to support sync and async plugins at the same time before fully able to use async at scale

[C-Loftus]

Thanks for your response clarifying that @francbartoli

fyi for others in the meantime, if you need to write your own plugin that uses async code, although the core itself / top level endpoints may not support it, you can achieve this in a way thats a little hacky but does work by creating your own global event loop and passing coroutines into it. This is not going to automatically make any underlying provider async, moreso just if you need to create a new async one. This essentially allows you to use await without being in an async function.

event_loop = asyncio.new_event_loop()

def await_(coro: Coroutine[Any, Any, T]) -> T:
    """
    await an asyncio coroutine, ensuring it works even if an event loop is already running.
    """
    return asyncio.run_coroutine_threadsafe(coro, loop=event_loop).result()

def loop_forever():
    """
    Start a shared event loop so we can run async code across providers
    """
    try:
        event_loop.run_forever()
    finally:
        event_loop.run_until_complete(event_loop.shutdown_asyncgens())
        event_loop.close()


loop_thread = threading.Thread(target=loop_forever)
loop_thread.daemon = True
loop_thread.start()

This I what I am doing for https://github.com/internetofwater/Western-Water-Datahub/