Support `--before-graceful-exit`

[abersheeran]

Summary

About https://github.com/encode/uvicorn/discussions/1936

The PR will solved https://stackoverflow.com/questions/58133694/graceful-shutdown-of-uvicorn-starlette-app-with-websockets

Checklist

• [x] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• [x] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• [x] I've updated the documentation accordingly.

[marcinsulikowski]

This PR adds a quite useful feature. One of the applications where I am using uvicorn has clients that use long polling to get notifications from the server using plain HTTP 1.1 and every time the application is stopped, it logs errors like this one:

2024-02-05 17:13:18,634 INFO Waiting for connections to close. (CTRL+C to force quit)
2024-02-05 17:13:23,635 ERROR Cancel 1 running task(s), timeout graceful shutdown exceeded
2024-02-05 17:13:23,638 INFO Waiting for application shutdown.
2024-02-05 17:13:23,652 ERROR Exception in ASGI application
Traceback (most recent call last):
  File "anyio/streams/memory.py", line 98, in receive
  File "anyio/streams/memory.py", line 93, in receive_nowait
anyio.WouldBlock

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "uvicorn/protocols/http/h11_impl.py", line 408, in run_asgi
  File "uvicorn/middleware/proxy_headers.py", line 84, in __call__
  File "fastapi/applications.py", line 1106, in __call__
  (...)
  File "anyio/streams/memory.py", line 106, in receive
  File "anyio/_backends/_asyncio.py", line 1778, in wait
  File "asyncio/locks.py", line 212, in wait
asyncio.exceptions.CancelledError: Task cancelled, timeout graceful shutdown exceeded

The hook added by this PR would make it possible to avoid such errors without any tricks like patching uvicorn's internal methods.

[adriangb]

Could you use https://www.uvicorn.org/deployment/#running-programmatically?

never mind I have had misunderstood the problem

[abersheeran]

@Kludex Do you have any other opinions? I noticed that you added a "hold" tag.

[Kludex]

Yes, we didn't discuss this properly.

Give me a chance to review the previous issues, and discussions, please.

[abersheeran]

If there is no problem, can this PR be merged? It solves a problem that has been around for years.

[Kludex]

I would like to take a look first.

[abersheeran]

ping @Kludex