diff options
Diffstat (limited to 'develop/print.html')
| -rw-r--r-- | develop/print.html | 152 |
1 files changed, 142 insertions, 10 deletions
diff --git a/develop/print.html b/develop/print.html index 6b1d017a88..6eb0d105c1 100644 --- a/develop/print.html +++ b/develop/print.html @@ -9590,6 +9590,7 @@ server admin.</p> } </code></pre> <p>The status will be one of <code>active</code>, <code>complete</code>, or <code>failed</code>.</p> +<p>If <code>status</code> is <code>failed</code> there will be a string <code>error</code> with the error message.</p> <h2 id="reclaim-disk-space-postgres"><a class="header" href="#reclaim-disk-space-postgres">Reclaim disk space (Postgres)</a></h2> <p>To reclaim the disk space and return it to the operating system, you need to run <code>VACUUM FULL;</code> on the database.</p> @@ -9927,6 +9928,9 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP <li><a href="admin_api/rooms.html#room-state-api">Room State API</a></li> <li><a href="admin_api/rooms.html#delete-room-api">Delete Room API</a> <ul> +<li><a href="admin_api/rooms.html#version-1-old-version">Version 1 (old version)</a></li> +<li><a href="admin_api/rooms.html#version-2-new-version">Version 2 (new version)</a></li> +<li><a href="admin_api/rooms.html#status-of-deleting-rooms">Status of deleting rooms</a></li> <li><a href="admin_api/rooms.html#undoing-room-shutdowns">Undoing room shutdowns</a></li> </ul> </li> @@ -10283,10 +10287,10 @@ leave the room without any information.</p> as room administrator and will contain a message explaining what happened. Users invited to the new room will have power level <code>-10</code> by default, and thus be unable to speak.</p> <p>If <code>block</code> is <code>true</code>, 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 <code>block</code> is <code>false</code>, attempting to delete an unknown room is -invalid and will be rejected as a bad request.</p> +This option can in <a href="admin_api/rooms.html#version-1-old-version">Version 1</a> 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 <code>block</code> is <code>false</code>, attempting to +delete an unknown room is invalid and will be rejected as a bad request.</p> <p>This API will remove all trace of the old room from your database after removing all local users. If <code>purge</code> is <code>true</code> (the default), all traces of the old room will be removed from your database after removing all local users. If you do not want @@ -10295,6 +10299,14 @@ Depending on the amount of history being purged, a call to the API may take several minutes or longer.</p> <p>The local server will only have the power to move local user and room aliases to the new room. Users on other servers will be unaffected.</p> +<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a +server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p> +<h2 id="version-1-old-version"><a class="header" href="#version-1-old-version">Version 1 (old version)</a></h2> +<p>This version works synchronously. That means you only get the response once the server has +finished the action, which may take a long time. If you request the same action +a second time, and the server has not finished the first one, the second request will block. +This is fixed in version 2 of this API. The parameters are the same in both APIs. +This API will become deprecated in the future.</p> <p>The API is:</p> <pre><code>DELETE /_synapse/admin/v1/rooms/<room_id> </code></pre> @@ -10307,8 +10319,6 @@ the new room. Users on other servers will be unaffected.</p> "purge": true } </code></pre> -<p>To use it, you will need to authenticate by providing an <code>access_token</code> for a -server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p> <p>A response body like the following is returned:</p> <pre><code class="language-json">{ "kicked_users": [ @@ -10322,6 +10332,31 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP "new_room_id": "!newroomid:example.com" } </code></pre> +<p>The parameters and response values have the same format as +<a href="admin_api/rooms.html#version-2-new-version">version 2</a> of the API.</p> +<h2 id="version-2-new-version"><a class="header" href="#version-2-new-version">Version 2 (new version)</a></h2> +<p><strong>Note</strong>: This API is new, experimental and "subject to change".</p> +<p>This version works asynchronously, meaning you get the response from server immediately +while the server works on that task in background. You can then request the status of the action +to check if it has completed.</p> +<p>The API is:</p> +<pre><code>DELETE /_synapse/admin/v2/rooms/<room_id> +</code></pre> +<p>with a body of:</p> +<pre><code class="language-json">{ + "new_room_user_id": "@someuser:example.com", + "room_name": "Content Violation Notification", + "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.", + "block": true, + "purge": true +} +</code></pre> +<p>The API starts the shut down and purge running, and returns immediately with a JSON body with +a purge id:</p> +<pre><code class="language-json">{ + "delete_id": "<opaque id>" +} +</code></pre> <p><strong>Parameters</strong></p> <p>The following parameters should be set in the URL:</p> <ul> @@ -10341,7 +10376,8 @@ invited to. Defaults to <code>Content Violation Notification</code></li> original room was shut down. Defaults to <code>Sharing illegal content on this server is not permitted and rooms in violation will be blocked.</code></li> <li><code>block</code> - Optional. If set to <code>true</code>, 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 <code>false</code>.</li> +even if they're not yet known to the homeserver (only with +<a href="admin_api/rooms.html#version-1-old-version">Version 1</a> of the API). Defaults to <code>false</code>.</li> <li><code>purge</code> - Optional. If set to <code>true</code>, it will remove all traces of the room from your database. Defaults to <code>true</code>.</li> <li><code>force_purge</code> - Optional, and ignored unless <code>purge</code> is <code>true</code>. If set to <code>true</code>, it @@ -10350,16 +10386,112 @@ use this unless a regular <code>purge</code> operation fails, as it could leave clients in a confused state.</li> </ul> <p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p> -<p><strong>Response</strong></p> +<h2 id="status-of-deleting-rooms"><a class="header" href="#status-of-deleting-rooms">Status of deleting rooms</a></h2> +<p><strong>Note</strong>: This API is new, experimental and "subject to change".</p> +<p>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).</p> +<h3 id="query-by-room_id"><a class="header" href="#query-by-room_id">Query by <code>room_id</code></a></h3> +<p>With this API you can get the status of all active deletion tasks, and all those completed in the last 24h, +for the given <code>room_id</code>.</p> +<p>The API is:</p> +<pre><code>GET /_synapse/admin/v2/rooms/<room_id>/delete_status +</code></pre> +<p>A response body like the following is returned:</p> +<pre><code class="language-json">{ + "results": [ + { + "delete_id": "delete_id1", + "status": "failed", + "error": "error message", + "shutdown_room": { + "kicked_users": [], + "failed_to_kick_users": [], + "local_aliases": [], + "new_room_id": null + } + }, { + "delete_id": "delete_id2", + "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" + } + } + ] +} +</code></pre> +<p><strong>Parameters</strong></p> +<p>The following parameters should be set in the URL:</p> +<ul> +<li><code>room_id</code> - The ID of the room.</li> +</ul> +<h3 id="query-by-delete_id"><a class="header" href="#query-by-delete_id">Query by <code>delete_id</code></a></h3> +<p>With this API you can get the status of one specific task by <code>delete_id</code>.</p> +<p>The API is:</p> +<pre><code>GET /_synapse/admin/v2/rooms/delete_status/<delete_id> +</code></pre> +<p>A response body like the following is returned:</p> +<pre><code class="language-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" + } +} +</code></pre> +<p><strong>Parameters</strong></p> +<p>The following parameters should be set in the URL:</p> +<ul> +<li><code>delete_id</code> - The ID for this delete.</li> +</ul> +<h3 id="response"><a class="header" href="#response">Response</a></h3> <p>The following fields are returned in the JSON response body:</p> <ul> +<li><code>results</code> - An array of objects, each containing information about one task. +This field is omitted from the result when you query by <code>delete_id</code>. +Task objects contain the following fields: +<ul> +<li><code>delete_id</code> - The ID for this purge if you query by <code>room_id</code>.</li> +<li><code>status</code> - The status will be one of: +<ul> +<li><code>shutting_down</code> - The process is removing users from the room.</li> +<li><code>purging</code> - The process is purging the room and event data from database.</li> +<li><code>complete</code> - The process has completed successfully.</li> +<li><code>failed</code> - The process is aborted, an error has occurred.</li> +</ul> +</li> +<li><code>error</code> - A string that shows an error message if <code>status</code> is <code>failed</code>. +Otherwise this field is hidden.</li> +<li><code>shutdown_room</code> - An object containing information about the result of shutting down the room. +<em>Note:</em> The result is shown after removing the room members. +The delete process can still be running. Please pay attention to the <code>status</code>. +<ul> <li><code>kicked_users</code> - An array of users (<code>user_id</code>) that were kicked.</li> <li><code>failed_to_kick_users</code> - An array of users (<code>user_id</code>) that that were not kicked.</li> -<li><code>local_aliases</code> - An array of strings representing the local aliases that were migrated from -the old room to the new.</li> +<li><code>local_aliases</code> - An array of strings representing the local aliases that were +migrated from the old room to the new.</li> <li><code>new_room_id</code> - A string representing the room ID of the new room, or <code>null</code> if no such room was created.</li> </ul> +</li> +</ul> +</li> +</ul> <h2 id="undoing-room-deletions"><a class="header" href="#undoing-room-deletions">Undoing room deletions</a></h2> <p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level, the structure can and does change without notice.</p> |