Improve lifespan control

[skeletorXVI]

Proposal

Provide means to better control the application lifetime.

e.g. provide exception classes similar to SystemExit to allow apps more control over their own lifetime.

Background

I'm currently working on a small project using FastAPI, during the startup process I run some checks and if they are not fulfilled the startup has to fail.
While it is possible to just raise an exception this actually results in a huge unwanted traceback, when this is the expected behavior and I just need Startup procedure failed, xyz not fulfilled.

I have solved this now by handling a special exception class in the Router.lifespan method by patching it on the Router instance created used by the FastAPI instance.

While this solution works for me, I believe this functionality should be build into Starlette.

My solution

import traceback
from typing import Any

from starlette.routing import Router
from starlette.types import Scope, Receive, Send


class LifespanError(BaseException)
    def __init__(self, message: str) -> None:
        self.message: str = message
        super().__init__(message)


def override_router_lifespan_method(router: Router) -> None:
    async def lifespan(self, scope: Scope, receive: Receive, send: Send) -> None:
        """
        Handle ASGI lifespan messages, which allows us to manage application
        startup and shutdown events.

        This method is a modification of the original lifespan method from starlette.
        """
        started = False
        app: Any = scope.get("app")
        await receive()
        try:
            async with self.lifespan_context(app) as maybe_state:
                if maybe_state is not None:
                    if "state" not in scope:
                        raise RuntimeError(
                            'The server does not support "state" in the lifespan scope.'
                        )
                    scope["state"].update(maybe_state)
                await send({"type": "lifespan.startup.complete"})
                started = True
                await receive()
        except LifespanError as e:
            if started:
                await send({"type": "lifespan.shutdown.failed", "message": e.message})
            else:
                await send({"type": "lifespan.startup.failed", "message": e.message})
            return
        except BaseException:
            exc_text = traceback.format_exc()
            if started:
                await send({"type": "lifespan.shutdown.failed", "message": exc_text})
            else:
                await send({"type": "lifespan.startup.failed", "message": exc_text})
            raise
        else:
            await send({"type": "lifespan.shutdown.complete"})

    router.lifespan = lifespan.__get__(router)

[dineshbvadhia]

This is the same problem I've been going round in circles for weeks. My code worked with the separate startup/shutdown functions but not with lifespan. I would like to test your proposed solution and have some usage questions. First, my problem and errors.

Command line arguments are passed to start up the system eg.

python vacation.py tourist --where london --when today

The arguments are validated in lifespan (startup). If the validation fails then the system isn't started and a message is sent to the user.

Instead an Exception in ASGI application error occurs with a lengthy traceback similar to the one below and the system hangs

INFO:     127.0.0.1:64225 - "GET /unexpected-error HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application

Traceback (most recent call last):
  File "...uvicorn\protocols\http\httptools_impl.py", line 399, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...uvicorn\middleware\proxy_headers.py", line 70, in __call__
    return await self.app(scope, receive, send)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...fastapi\applications.py", line 1054, in __call__
    await super().__call__(scope, receive, send)
  File "...starlette\applications.py", line 123, in __call__
    await self.middleware_stack(scope, receive, send)
  File "...starlette\middleware\errors.py", line 186, in __call__
    raise exc
  File "...starlette\middleware\errors.py", line 164, in __call__
    await self.app(scope, receive, _send)
  File "...starlette\middleware\exceptions.py", line 65, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "...starlette\_exception_handler.py", line 64, in wrapped_app
    raise exc
  File "...starlette\_exception_handler.py", line 53, in wrapped_app
    await app(scope, receive, sender)
  File "...starlette\routing.py", line 756, in __call__
    await self.middleware_stack(scope, receive, send)
  File "...starlette\routing.py", line 776, in app
    await route.handle(scope, receive, send)
  File "...starlette\routing.py", line 297, in handle
    await self.app(scope, receive, send)
  File "...starlette\routing.py", line 77, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "...starlette\_exception_handler.py", line 64, in wrapped_app
    raise exc
  File "...starlette\_exception_handler.py", line 53, in wrapped_app
    await app(scope, receive, sender)
  File "...starlette\routing.py", line 72, in app
    response = await func(request)
               ^^^^^^^^^^^^^^^^^^^
  File "...fastapi\routing.py", line 278, in app
    raw_response = await run_endpoint_function(
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...fastapi\routing.py", line 191, in run_endpoint_function
    return await dependant.call(**values)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...custom.py", line 66, in unexpected_error
    return {"value": 1 / 0}
                     ~~^~~
ZeroDivisionError: division by zero

[dineshbvadhia]

Wrt your proposed solution, how is it used? My configuration is simply:

router = APIRouter(prefix="/api", redirect_slashes=False)

@asynccontextmanager
async def lifespan(app: FastAPI):
	do_startup_stuff(sys.argv)
	yield
	do_shutdown_stuff()

app = FastAPI(lifespan=lifespan)
app.include_router(router)
add_exception_handler(
    app,
    logger=logger,
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "vacation:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Also, I use structlog as the logger and need to pass an error message from where the validation failed. Best ...

[dineshbvadhia]

Ok, got it mostly working. My router is different from the override lifespan router and changing the name of mine got it working.

There are problems with uvicorn not reloading, signal interrupt (ctrl-C) and logging which I'm trying to narrow down:

I disable uvicorn.error with logging.config but this causes override lifespan to hang. Keeping the default uvicorn logging works. But, reload and signal interrupt don't work with uvicorn.error enabled or disabled.

[skeletorXVI]

Ok, got it mostly working. My router is different from the override lifespan router and changing the name of mine got it working.

There are problems with uvicorn not reloading, signal interrupt (ctrl-C) and logging which I'm trying to narrow down:

I disable uvicorn.error with logging.config but this causes override lifespan to hang. Keeping the default uvicorn logging works. But, reload and signal interrupt don't work with uvicorn.error enabled or disabled.

I can only offer limited insight in to your problems. Modifying the minimal example you provided worked, including reloading. I run this code on 3 or 4 projects, reloading works with PyCharm's FastAPI Run Configuration but we don't override the default logger, so that might be a point to investigate.

The important thing is that the router passed to the override is the starlette router that is passed to the ASGI server.

[dineshbvadhia]

Ok thanks. Will investigate further. The uvicorn logger is a pain :(.

[dineshbvadhia]

Which version of uvicorn are you on?

[skeletorXVI]

I apologize for the late response, both projects currently using this solution use uvicorn==0.30.1

[adriangb]

Have you tried running your own event loop? https://github.com/adriangb/asapi?tab=readme-ov-file#run-in-your-event-loop

[dineshbvadhia]

No and I will try it. From the example, is asapi dispensing with the explicit use of lifespan and instead resources can be initialised in the async def main() block?

[adriangb]

Yes exactly

[dineshbvadhia]

I'll carry on discussion on the asapi site. Best ...