From fb4ef079280960d1f14958c01703dfb86ec33b59 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Wed, 6 Mar 2024 16:37:10 +0100 Subject: feat(federation): Add capabilities for the federation feature and configs Signed-off-by: Joas Schilling --- docs/avatar.md | 2 ++ docs/capabilities.md | 5 +++++ docs/chat.md | 8 ++++++++ docs/conversation.md | 23 +++++++++++++++++++++++ docs/global.md | 16 ++++++++++++++++ docs/participant.md | 5 +++++ docs/reaction.md | 3 +++ 7 files changed, 62 insertions(+) (limited to 'docs') diff --git a/docs/avatar.md b/docs/avatar.md index b63b8e145..7fc908c44 100644 --- a/docs/avatar.md +++ b/docs/avatar.md @@ -70,6 +70,7 @@ ## Get conversations avatar (binary) * Required capability: `avatar` +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/room/{token}/avatar` @@ -82,6 +83,7 @@ ## Get dark mode conversations avatar (binary) * Required capability: `avatar` +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/room/{token}/avatar/dark` diff --git a/docs/capabilities.md b/docs/capabilities.md index c0d746cd7..1f8987a1e 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -144,3 +144,8 @@ * `edit-messages` - Whether messages can be edited (restricted to 24 hours after posting) * `silent-send-state` - Whether messages contain a flag that they were sent silently * `chat-read-last` - Whether chat can be marked read without giving a message ID (will fall back to the conversations last message ID) +* `federation-v1` - Whether basic chatting is possible with federation +* `config => federation => enabled` - Boolean, whether federation is enabled on instance +* `config => federation => incoming-enabled` - Boolean, whether users are allowed to be invited into federated conversations on other servers +* `config => federation => outgoing-enabled` - Boolean, whether users are allowed to invited federated users of other servers into conversations +* `config => federation => only-trusted-servers` - Boolean, whether federation invites are limited to trusted servers diff --git a/docs/chat.md b/docs/chat.md index 358e0b976..4a02511cf 100644 --- a/docs/chat.md +++ b/docs/chat.md @@ -10,6 +10,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 It is therefor recommended to use `format=json` or send the `Accept: application/json` header, to receive a JSON response. +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/chat/{token}` * Data: @@ -90,6 +91,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 to receive a JSON response. * Required capability: `chat-get-context` +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/chat/{token}/{messageId}/context` * Data: @@ -115,6 +117,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 13 ## Sending a new chat message +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/chat/{token}` * Data: @@ -284,6 +287,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob ## Deleting a chat message * Required capability: `delete-messages` - `rich-object-delete` indicates if shared objects can be deleted from the chat +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/chat/{token}/{messageId}` @@ -313,6 +317,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob ## Editing a chat message * Required capability: `edit-messages` +* Federation capability: `federation-v1` * Method: `PUT` * Endpoint: `/chat/{token}/{messageId}` * Data: @@ -412,6 +417,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob ## Mark chat as read * Required capability: `chat-read-marker` +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/chat/{token}/read` * Data: @@ -439,6 +445,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob ## Mark chat as unread * Required capability: `chat-unread` +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/chat/{token}/read` @@ -460,6 +467,7 @@ See [OCP\RichObjectStrings\Definitions](https://github.com/nextcloud/server/blob ## Get mention autocomplete suggestions +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/chat/{token}/mentions` * Data: diff --git a/docs/conversation.md b/docs/conversation.md index a043aa9d5..bcb13ce24 100644 --- a/docs/conversation.md +++ b/docs/conversation.md @@ -365,6 +365,7 @@ Get all (for moderators and in case of "free selection") or the assigned breakou ## Add conversation to favorites * Required capability: `favorites` +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/room/{token}/favorite` @@ -377,6 +378,7 @@ Get all (for moderators and in case of "free selection") or the assigned breakou ## Remove conversation from favorites * Required capability: `favorites` +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/room/{token}/favorite` @@ -389,6 +391,7 @@ Get all (for moderators and in case of "free selection") or the assigned breakou ## Set notification level * Required capability: `notification-levels` +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/room/{token}/notify` * Data: @@ -478,3 +481,23 @@ Get all (for moderators and in case of "free selection") or the assigned breakou + `400 Bad Request` When the conversation is a breakout room + `403 Forbidden` When the current user is not a moderator/owner or the conversation is not a public conversation + `404 Not Found` When the conversation could not be found for the participant + +## Get conversation capabilities + +* Required capability: `federation-v1` +* Method: `GET` +* Endpoint: `/room/{token}/capabilities` + +* Response: + - Status code: + + `200 OK` Get capabilities + + `404 Not Found` When the conversation could not be found for the participant + + - Header: + +| field | type | Description | +|-------------------------------|--------|--------------------------------------------------------------------------------------------| +| `X-Nextcloud-Talk-Proxy-Hash` | string | Sha1 value over the capabilities in case the conversation is hosted **on another server**. | +| `X-Nextcloud-Talk-Hash` | string | Sha1 value over the capabilities in case the conversation is hosted **on this server**. | + + - Data: Server capabilities limited to the `spreed` sub-array or an empty array in case the app is disabled (for the user) diff --git a/docs/global.md b/docs/global.md index a1e728a76..6ae8ff84a 100644 --- a/docs/global.md +++ b/docs/global.md @@ -40,3 +40,19 @@ From time to time it is unavoidable to break compatibility. In such cases we try + `426 Upgrade Required` - Body: + `ocs.meta.message` contains the minimum required version of the used client + +## Federation - Not supported + +Endpoints without a "Federation capability: `federation-vX`" will return a `406 Not Acceptable` status code, when called with tokens that actually refer to a so-called proxy conversation on the local server. + +* Response: + - Status code: + + `406 Not Acceptable` + +## Federation - Remote error + +When a request is performed on a proxy conversation and the host can not be reached `422 Unprocessable Content` will be returned. The only exception will be leaving the room, where the request will still execute it's part locally so the user is no longer bothered. A background job will be queued to retry informing the remote server about the leave automatically. + +* Response: + - Status code: + + `422 Unprocessable Content` diff --git a/docs/participant.md b/docs/participant.md index d46380863..157f420fa 100644 --- a/docs/participant.md +++ b/docs/participant.md @@ -7,6 +7,7 @@ ## Get list of participants in a conversation +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/room/{token}/participants` * Data: @@ -108,6 +109,7 @@ ## Remove yourself from a conversation +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/room/{token}/participants/self` @@ -119,6 +121,7 @@ ## Join a conversation (available for call and chat) +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/room/{token}/participants/active` * Data: @@ -165,6 +168,7 @@ ## Set session state * Required capability: `session-state` +* Federation capability: `federation-v1` * Method: `PUT` * Endpoint: `/room/{token}/participants/state` @@ -176,6 +180,7 @@ ## Leave a conversation (not available for call and chat anymore) +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/room/{token}/participants/active` diff --git a/docs/reaction.md b/docs/reaction.md index 0185886ff..1373c249f 100644 --- a/docs/reaction.md +++ b/docs/reaction.md @@ -5,6 +5,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 ## React to a message * Required capability: `reactions` +* Federation capability: `federation-v1` * Method: `POST` * Endpoint: `/reaction/{token}/{messageId}` * Data: @@ -33,6 +34,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 ## Delete a reaction * Required capability: `reactions` +* Federation capability: `federation-v1` * Method: `DELETE` * Endpoint: `/reaction/{token}/{messageId}` * Data: @@ -60,6 +62,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: since Nextcloud 24 ## Retrieve reactions of a message by type * Required capability: `reactions` +* Federation capability: `federation-v1` * Method: `GET` * Endpoint: `/reaction/{token}/{messageId}` * Data: -- cgit v1.2.3