Convert delete room admin API to async endpoint

docs/admin_api/purge_history_api.md

@@ -69,6 +69,7 @@ This API returns a JSON body like the following:
 ```
 
 The status will be one of `active`, `complete`, or `failed`.
+If `status` is `failed` there will be a string `error` with the error message.
 
 ## Reclaim disk space (Postgres)
 

docs/admin_api/rooms.md

@@ -400,10 +400,10 @@ as room administrator and will contain a message explaining what happened. Users
 to the new room will have power level `-10` by default, and thus be unable to speak.
 
 If `block` is `true`, users will be prevented from joining the old room.
-This option can also be used to pre-emptively block a room, even if it's unknown
-to this homeserver. In this case, the room will be blocked, and no further action
-will be taken. If `block` is `false`, attempting to delete an unknown room is
-invalid and will be rejected as a bad request.
+This option can in [Version 1](#version-1-old-version) also be used to pre-emptively
+block a room, even if it's unknown to this homeserver. In this case, the room will be
+blocked, and no further action will be taken. If `block` is `false`, attempting to
+delete an unknown room is invalid and will be rejected as a bad request.
 
 This API will remove all trace of the old room from your database after removing
 all local users. If `purge` is `true` (the default), all traces of the old room will
@@ -494,7 +494,7 @@ a purge id:
 
 ```json
 {
-    "purge_id": "<opaque id>"
+    "delete_id": "<opaque id>"
 }
 ```
 
@@ -519,7 +519,8 @@ The following JSON body parameters are available:
                is not permitted and rooms in violation will be blocked.`
 * `block` - Optional. If set to `true`, this room will be added to a blocking list,
             preventing future attempts to join the room. Rooms can be blocked
-            even if they're not yet known to the homeserver. Defaults to `false`.
+            even if they're not yet known to the homeserver (only with
+            [Version 1](#version-1-old-version) of the API). Defaults to `false`.
 * `purge` - Optional. If set to `true`, it will remove all traces of the room from your database.
             Defaults to `true`.
 * `force_purge` - Optional, and ignored unless `purge` is `true`. If set to `true`, it
@@ -537,9 +538,9 @@ It is possible to query the status of the background task for deleting rooms.
 The status can be queried up to 24 hours after completion of the task,
 or until Synapse is restarted (whichever happens first).
 
+### Query by `room_id`
+
 With this API you can get the status of all tasks the last 24h for this `room_id`.
-If you want only get the status of one specific task, you can also use
-the [Purge status query API](purge_history_api.md#Purge-status-query).
 
 The API is:
 
@@ -551,20 +552,21 @@ A response body like the following is returned:
 
 ```json
 {
-    "delete_status": [
+    "results": [
         {
-            "purge_id": "purgeid1",
+            "delete_id": "delete_id1",
             "status": "failed",
-            "result": {
+            "error": "error message",
+            "shutdown_room": {
                 "kicked_users": [],
                 "failed_to_kick_users": [],
                 "local_aliases": [],
                 "new_room_id": null
             }
         }, {
-            "purge_id": "purgeid2",
-            "status": "active",
-            "result": {
+            "delete_id": "delete_id2",
+            "status": "purging",
+            "shutdown_room": {
                 "kicked_users": [
                     "@foobar:example.com"
                 ],
@@ -586,25 +588,65 @@ The following parameters should be set in the URL:
 
 * `room_id` - The ID of the room.
 
-**Response**
+### Query by `delete_id`
+
+With this API you can get the status of one specific task by `delete_id`.
+
+The API is:
+
+```
+GET /_synapse/admin/v2/rooms/delete_status/<delete_id>
+```
+
+A response body like the following is returned:
+
+```json
+{
+    "status": "purging",
+    "shutdown_room": {
+        "kicked_users": [
+            "@foobar:example.com"
+        ],
+        "failed_to_kick_users": [],
+        "local_aliases": [
+            "#badroom:example.com",
+            "#evilsaloon:example.com"
+        ],
+        "new_room_id": "!newroomid:example.com"
+    }
+}
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `delete_id` - The ID for this delete.
+
+### Response
 
 The following fields are returned in the JSON response body:
 
-- `delete_status` - An array of objects, each containing information about one task.
+- `results` - An array of objects, each containing information about one task.
+  This field is omitted from the result when you query by `delete_id`.
   Task objects contain the following fields:
+  - `delete_id` - The ID for this purge if you query by `room_id`.
   - `status` - The status will be one of:
-    - `remove members` - The process is removing users from the `room_id`.
-    - `active` - The process is purging the room from database.
+    - `shutting_down` - The process is removing users from the room.
+    - `purging` - The process is purging the room and event data from database.
     - `complete` - The process has completed successfully.
     - `failed` - The process is aborted, an error has occurred.
-  - `result` - An object containing information about the result of shutting down the room.
-    *Note:* The result is shown after removing the room members. The delete process can
-    still be running. Please pay attention to the `status`.
+  - `error` - A string that shows an error message if `status` is `failed`.
+    Otherwise this field is hidden.
+  - `shutdown_room` - An object containing information about the result of shutting down the room.
+    *Note:* The result is shown after removing the room members.
+    The delete process can still be running. Please pay attention to the `status`.
     - `kicked_users` - An array of users (`user_id`) that were kicked.
     - `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked.
     - `local_aliases` - An array of strings representing the local aliases that were
-    migrated from the old room to the new.
-    - `new_room_id` - A string representing the room ID of the new room.
+      migrated from the old room to the new.
+    - `new_room_id` - A string representing the room ID of the new room, or `null` if
+      no such room was created.
 
 ## Undoing room deletions