Add `@cancellable` decorator, for use on request handlers (#12586)

Signed-off-by: Sean Quah <seanq@element.io>

Add `@cancellable` decorator, for use on request handlers (#12586)
5c00151c · Sean Quah · GitHub · 2aad0ae5 · 5c00151c · 5c00151c
Unverified Commit 5c00151c authored 2 years ago by Sean Quah Committed by GitHub 2 years ago
--- a/changelog.d/12586.misc
+++ b/changelog.d/12586.misc
+Add `@cancellable` decorator, for use on endpoint methods that can be cancelled when clients disconnect.
--- a/synapse/http/server.py
+++ b/synapse/http/server.py
@@ -33,6 +33,7 @@ from typing import (
    Optional,
    Pattern,
    Tuple,
+    TypeVar,
    Union,
 )
@@ -92,6 +93,66 @@ HTML_ERROR_TEMPLATE = """<!DOCTYPE html>
 HTTP_STATUS_REQUEST_CANCELLED = 499
+F = TypeVar("F", bound=Callable[..., Any])
+_cancellable_method_names = frozenset(
+    {
+        # `RestServlet`, `BaseFederationServlet` and `BaseFederationServerServlet`
+        # methods
+        "on_GET",
+        "on_PUT",
+        "on_POST",
+        "on_DELETE",
+        # `_AsyncResource`, `DirectServeHtmlResource` and `DirectServeJsonResource`
+        # methods
+        "_async_render_GET",
+        "_async_render_PUT",
+        "_async_render_POST",
+        "_async_render_DELETE",
+        "_async_render_OPTIONS",
+        # `ReplicationEndpoint` methods
+        "_handle_request",
+    }
+)
+def cancellable(method: F) -> F:
+    """Marks a servlet method as cancellable.
+    Methods with this decorator will be cancelled if the client disconnects before we
+    finish processing the request.
+    During cancellation, `Deferred.cancel()` will be invoked on the `Deferred` wrapping
+    the method. The `cancel()` call will propagate down to the `Deferred` that is
+    currently being waited on. That `Deferred` will raise a `CancelledError`, which will
+    propagate up, as per normal exception handling.
+    Before applying this decorator to a new endpoint, you MUST recursively check
+    that all `await`s in the function are on `async` functions or `Deferred`s that
+    handle cancellation cleanly, otherwise a variety of bugs may occur, ranging from
+    premature logging context closure, to stuck requests, to database corruption.
+    Usage:
+        class SomeServlet(RestServlet):
+            @cancellable
+            async def on_GET(self, request: SynapseRequest) -> ...:
+                ...
+    """
+    if method.__name__ not in _cancellable_method_names:
+        raise ValueError(
+            "@cancellable decorator can only be applied to servlet methods."
+        )
+    method.cancellable = True  # type: ignore[attr-defined]
+    return method
+def is_method_cancellable(method: Callable[..., Any]) -> bool:
+    """Checks whether a servlet method has the `@cancellable` flag."""
+    return getattr(method, "cancellable", False)
 def return_json_error(f: failure.Failure, request: SynapseRequest) -> None:
    """Sends a JSON error response to clients."""