Add @cancellable decorator, for use on endpoint methods that can be cancelled when clients disconnect

[squahtx]

Best reviewed commit by commit.
I'm going to try to break this up into smaller PRs.

---

Add a @cancellable decorator that can be used on async HTTP endpoints.

In Synapse, we have 5 ways of defining async HTTP endpoints:

• RestServlet subclasses with on_$METHOD methods
• BaseFederationServlet subclasses with on_$METHOD methods
• ReplicationEndpoint subclasses with a _handle_request
  implementation
• DirectServe{Html,Json}Resource subclasses with
  _async_render_$METHOD methods

All of these get invoked indirectly by _AsyncResource.render, which
starts the async processing.
DirectServeHtmlResource and DirectServeJsonResource inherit from
_AsyncResource directly, while the rest register themselves using
register_paths on a JsonResource, which inherits from
_AsyncResource.

---

Going to split this up into smaller PRs like so:

#12586 (merged)
2780bedb5185d729d03faa4cc4739862609539c4 Add `@cancellable` decorator, for use on request handlers
|
|   #12587 (merged)
|   1ce7dbf42c24c139683e58cd79d0ad6f16502219 Improve logging for cancelled requests
|   |
|   |   #12588 (merged)
|   |   0dc4178587b65313c7d81b5f4880082f1c2e3d11 Add ability to cancel disconnected requests to `SynapseRequest`
|   |   |   |
|   |   |   v
|   |   |   #12694 (merged)
|   |   |   5a9991c0f93b71b5eac8d6c47b1ba6d5bb2004c7 Capture the `Deferred` for request cancellation in `_AsyncResource`
|   |   |   |
|   |   |   |   #12630 (merged)
|   +---------->3d89472339c9d506fa87ad21d57f502ff4b9c342 Expose the `SynapseRequest` from `FakeChannel` for testing disconnection
|   |   |   |   2bbad2930db9b373b149f295d71d5bb49748c1ed Add helper class for testing request cancellation
|   |   |   |   |
+<--+<--+<--+<--+
|
|   #12698 (merged)
+-->46cdb4bd0746df6aad0b2408beb35b38b5a94c18 Respect the `@cancellable` flag for `DirectServe{Html,Json}Resource`s
|   92b7b17c3df6d71dea82e64e8c97b81c6cd1a76b Test the `@cancellable` flag on `DirectServe{Html,Json}Resource` methods
|
|   #12699 (merged)
+-->2326bbf0999e99b57dafcebd966dd9bd942c52a2 Respect the `@cancellable` flag for `RestServlet`s and `BaseFederationServlet`s
|   6720b8780f57c4d361a82fb6a539781f4f0d63f6 Test the `@cancellable` flag on `RestServlet` methods
|   3544cfdaa192831cc59684abd5618d7748bd6f1f Fix `make_signed_federation_request` turning empty dicts into `b""`
|   89cb0f140e5d81b3f3f049029ffeb65fa36d2c61 Test the `@cancellable` flag on `BaseFederationServlet` methods
|   |
|   v
|   #12705 (merged)
|   c3eb1e3358be4453c36426ac5b117c9ae7d0fec3 Complain if a federation endpoint has the `@cancellable` flag
|   342a502a1e08968dd2643af46eaf4105b086edf9 Disable tests for the `@cancellable` flag on `BaseFederationServlet` methods
|
|   #12700 (merged)
+-->62d3b915a5eb110b36e75107d77dd161305bf7e9 Respect the `@cancellable` flag for `ReplicationEndpoint`s
    d3f75f3c9430059a4b9e70b56eb344d70b6c693f Test the `@cancellable` flag on `ReplicationEndpoint._handle_request`

[squahtx]

I wonder if we should add an explicit cancellable parameter to register_paths instead.
There are a few places where we call register_paths manually, with callbacks that don't match the ^on_(GET|PUT|POST|DELETE)$ pattern, eg.

synapse/synapse/rest/client/room.py

Lines 133 to 138 in 4bc8cb4

	http_server.register_paths(
	"GET",
	client_patterns(no_state_key, v1=True),
	self.on_GET_no_state_key,
	self.__class__.__name__,
	)

There we have the option of either relaxing the validation in the @cancellable decorator or adding an explicit cancellable parameter to register_paths.

The benefit of relaxing the decorator validation is that it's more obvious that on_GET_no_state_key has cancellation enabled:

    @cancellable
    def on_GET_no_state_key(
        self, request: SynapseRequest, room_id: str, event_type: str
    ) -> Awaitable[Tuple[int, JsonDict]]:
        return self.on_GET(request, room_id, event_type, "")

    @cancellable
    async def on_GET(

[squahtx]

All reviewed and merged now. Thank you to everyone who reviewed!