Merge pull request #1817 from matrix-org/neilj/remove_presence_lists

remove references to presence lists

api/client-server/presence.yaml

@@ -136,103 +136,3 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - Presence
-  "/presence/list/{userId}":
-    post:
-      summary: Add or remove users from this presence list.
-      description: |-
-        Adds or removes users from this presence list.
-      operationId: modifyPresenceList
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence list is being modified.
-          required: true
-          x-example: "@alice:example.com"
-        - in: body
-          name: presence_diff
-          description: The modifications to make to this presence list.
-          required: true
-          schema:
-            type: object
-            example: {
-                "invite": [
-                  "@bob:matrix.org"
-                ],
-                "drop": [
-                  "@alice:matrix.org"
-                ]
-              }
-            properties:
-              invite:
-                type: array
-                description: A list of user IDs to add to the list.
-                items:
-                  type: string
-                  description: A list of user IDs.
-              drop:
-                type: array
-                description: A list of user IDs to remove from the list.
-                items:
-                  type: string
-                  description: A list of user IDs.
-      responses:
-        200:
-          description: The list was updated.
-          examples:
-            application/json: {
-              }
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
-      tags:
-        - Presence
-    get:
-      summary: Get presence events for this presence list.
-      description: |-
-        Retrieve a list of presence events for every user on this list.
-      operationId: getPresenceForList
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence list should be retrieved.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: A list of presence events for this list.
-          examples:
-            application/json: [
-                {
-                  "content": {
-                    "last_active_ago": 395,
-                    "presence": "offline",
-                    "user_id": "@alice:matrix.org"
-                  },
-                  "type": "m.presence"
-                },
-                {
-                  "content": {
-                    "last_active_ago": 16874,
-                    "presence": "online",
-                    "user_id": "@marisa:matrix.org",
-                    "currently_active": true
-                  },
-                  "type": "m.presence"
-                }
-              ]
-          schema:
-            type: array
-            items:
-              type: object
-              title: PresenceEvent
-              allOf:
-                - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
-      tags:
-        - Presence

api/server-server/definitions/event-schemas/m.device_list_update.yaml

@@ -21,7 +21,7 @@ description: |-
 
 # FIXME: It's very unclear why we have this API surface for synchronising
 # device lists, rather than just using a room (which could also be used for
-# presence lists, profile info, etc).  But documenting what we have for now...
+# profile info, etc).  But documenting what we have for now...
 
 allOf:
   - $ref: ../edu.yaml

changelogs/client_server/newsfragments/1817.deprecation

@@ -0,0 +1 @@
+Remove references to presence lists

specification/modules/presence.rst

@@ -26,14 +26,8 @@ Each user has the concept of presence information. This encodes:
 
 This information is collated from both per-device (``online``, ``idle``,
 ``last_active``) and per-user (status) data, aggregated by the user's homeserver
-and transmitted as an ``m.presence`` event. This is one of the few events which
-are sent *outside the context of a room*. Presence events are sent to all users
-who subscribe to this user's presence through a presence list or by sharing
-membership of a room.
-
-A presence list is a list of user IDs whose presence the user wants to follow.
-To be added to this list, the user being added must be invited by the list owner
-who must accept the invitation.
+and transmitted as an ``m.presence`` event. Presence events are sent to
+interested parties where users share a room membership.
 
 User's presence state is represented by the ``presence`` key, which is an enum
 of one of the following:
@@ -53,17 +47,10 @@ Events
 Client behaviour
 ----------------
 
-Clients can manually set/get their presence/presence list using the HTTP APIs
-listed below.
+Clients can manually set/get their presence using the HTTP APIs listed below.
 
 {{presence_cs_http_api}}
 
-Server behaviour
-----------------
-
-Each user's homeserver stores a "presence list" per user. Once a user accepts
-a presence list, both user's HSes must track the subscription.
-
 Last active ago
 ~~~~~~~~~~~~~~~
 The server maintains a timestamp of the last time it saw a pro-active event from

specification/server_server_api.rst

@@ -907,15 +907,8 @@ The server API for presence is based entirely on exchange of the following
 EDUs. There are no PDUs or Federation Queries involved.
 
 Servers should only send presence updates for users that the receiving server
-would be interested in. This can include the receiving server sharing a room
-with a given user, or a user on the receiving server has added one of the
-sending server's users to their presence list.
-
-Clients may define lists of users that they are interested in via "Presence
-Lists" through the `Client-Server API`_. When users are added to a presence
-list, a ``m.presence_invite`` EDU is sent to them. The user may then accept
-or deny their involvement in the list by sending either an ``m.presence_accept``
-or ``m.presence_deny`` EDU back.
+would be interested in. Such as the receiving server sharing a room
+with a given user.
 
 .. TODO-doc
   - Explain the timing-based round-trip reduction mechanism for presence
@@ -925,13 +918,6 @@ or ``m.presence_deny`` EDU back.
 
 {{definition_ss_event_schemas_m_presence}}
 
-{{definition_ss_event_schemas_m_presence_invite}}
-
-{{definition_ss_event_schemas_m_presence_accept}}
-
-{{definition_ss_event_schemas_m_presence_deny}}
-
-
 Receipts
 --------
 
@@ -1009,7 +995,7 @@ which should be used to correlate with subsequent ``m.device_list_update`` EDUs.
 
 .. TODO: this whole thing desperately feels like it should just be state in a room,
   rather than inventing a whole different DAG.  The same room could be used for
-  profiles, presence lists, etc.
+  profiles etc.
 
 {{user_devices_ss_http_api}}