Spec for MSC4267: Automatically forgetting rooms on leave (#2292)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

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).

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

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.

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: []