diff --git a/changelogs/client_server/newsfragments/2292.feature b/changelogs/client_server/newsfragments/2292.feature new file mode 100644 index 00000000..6547782b --- /dev/null +++ b/changelogs/client_server/newsfragments/2292.feature @@ -0,0 +1 @@ +Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 1bc8fdbc..cb7e7391 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2619,6 +2619,40 @@ An example of the capability API's response for this capability is: } ``` +### `m.forget_forced_upon_leave` capability + +{{% added-in v="1.18" %}} + +This capability has a single flag, `enabled`, which indicates whether or +not the server automatically forgets rooms which the user has left. + +When `enabled` is `true` and the user leaves a room, the server will automatically +forget the room — just as if the user had called [`/forget`](#post_matrixclientv3roomsroomidforget) +themselves. This behavior applies irrespective of whether the user has left the +room on their own (through [`/leave`](#post_matrixclientv3roomsroomidleave)) or +has been kicked or banned from the room by another user. + +When `enabled` is `false`, the server does not automatically forget rooms +upon leave. In this case, clients MAY distinguish the actions of leaving +and forgetting a room in their UI. Similarly, clients MAY retrieve and +visualize left but unforgotten rooms using a [filter](#filtering) with +`include_leave = true`. + +When the capability or the `enabled` property are not present, clients SHOULD +assume that the server does not automatically forget rooms. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.forget_forced_upon_leave": { + "enabled": true + } + } +} +``` + ### `m.room_versions` capability This capability describes the default and available room versions a diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 2e8c8849..f73e8b46 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -50,6 +50,12 @@ paths: m.change_password: $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change their password. + m.forget_forced_upon_leave: + x-addedInMatrixVersion: "1.18" + $ref: '#/components/schemas/booleanCapability' + description: |- + Capability to indicate if the server automatically forgets rooms once the user + leaves. m.room_versions: type: object description: The room versions the server supports. diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index 6bdadb08..edb8ffd3 100644 --- a/data/api/client-server/leaving.yaml +++ b/data/api/client-server/leaving.yaml @@ -19,6 +19,10 @@ paths: "/rooms/{roomId}/leave": post: summary: Stop the requesting user participating in a particular room. + x-changedInMatrixVersion: + "1.18": |- + Servers may additionally forget the room provided that they make this behavior + transparent. description: |- This API stops a user participating in a particular room. @@ -29,8 +33,15 @@ paths: If the user was invited to the room, but had not joined, this call serves to reject the invite. - The user will still be allowed to retrieve history from the room which - they were previously allowed to see. + Servers MAY additionally forget the room when this endpoint is called – + just as if the user had also invoked [`/forget`](/client-server-api/#post_matrixclientv3roomsroomidforget). + Servers that do this, MUST inform clients about this behavior using the + [`m.forget_forced_upon_leave`](/client-server-api/#mforget_forced_upon_leave-capability) + capability. + + If the server doesn't automatically forget the room, the user will still be + allowed to retrieve history from the room which they were previously allowed + to see. operationId: leaveRoom security: - accessTokenQuery: []