diff options
| author | Sean Quah <8349537+squahtx@users.noreply.github.com> | 2022-05-10 14:05:22 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-05-10 14:05:22 +0100 |
| commit | 5c00151c28367cb091c408d02b275e7859bd4ace (patch) | |
| tree | 973ec7a7fcdf7fd202c3ba1fde7b97ff14fe3d75 | |
| parent | Merge tag 'v1.59.0rc1' into develop (diff) | |
| download | synapse-5c00151c28367cb091c408d02b275e7859bd4ace.tar.xz | |
Add `@cancellable` decorator, for use on request handlers (#12586)
Signed-off-by: Sean Quah <seanq@element.io>
| -rw-r--r-- | changelog.d/12586.misc | 1 | ||||
| -rw-r--r-- | synapse/http/server.py | 61 |
2 files changed, 62 insertions, 0 deletions
diff --git a/changelog.d/12586.misc b/changelog.d/12586.misc new file mode 100644 index 0000000000..d26e332305 --- /dev/null +++ b/changelog.d/12586.misc @@ -0,0 +1 @@ +Add `@cancellable` decorator, for use on endpoint methods that can be cancelled when clients disconnect. diff --git a/synapse/http/server.py b/synapse/http/server.py index 657bffcddd..8c96f2196e 100644 --- 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.""" |