From bf2b6e6daac2fc7cd7240050737cf372ed6ac60b Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 28 Jan 2019 15:05:10 +0000 Subject: [PATCH 1/4] remove references to presence lists --- api/client-server/presence.yaml | 100 ------------------ .../event-schemas/m.device_list_update.yaml | 2 +- specification/modules/presence.rst | 19 +--- specification/server_server_api.rst | 20 +--- 4 files changed, 7 insertions(+), 134 deletions(-) diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index 91b75c6a8..874ac59b9 100644 --- a/api/client-server/presence.yaml +++ b/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 diff --git a/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/api/server-server/definitions/event-schemas/m.device_list_update.yaml index f11e957e2..d511bfae7 100644 --- a/api/server-server/definitions/event-schemas/m.device_list_update.yaml +++ b/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 diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 822b298d4..4873776a3 100644 --- a/specification/modules/presence.rst +++ b/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 event 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 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 09ad333fb..7457cfd4e 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1012,15 +1012,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 @@ -1030,13 +1023,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 -------- @@ -1114,7 +1100,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}} From ed68f940cd899183d36a19ed39a165a2fdaf4f8f Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 28 Jan 2019 17:49:20 +0000 Subject: [PATCH 2/4] towncrier --- changelogs/client_server/newsfragments/1817.deprecation | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1817.deprecation diff --git a/changelogs/client_server/newsfragments/1817.deprecation b/changelogs/client_server/newsfragments/1817.deprecation new file mode 100644 index 000000000..9a888e85d --- /dev/null +++ b/changelogs/client_server/newsfragments/1817.deprecation @@ -0,0 +1 @@ +Remove references to presence lists From c09fa6845ea6394588a10ee31115533c1620b65c Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 29 Jan 2019 18:23:30 +0000 Subject: [PATCH 3/4] Update presence.rst --- specification/modules/presence.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 4873776a3..53a335509 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -26,7 +26,7 @@ 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. Presence event are sent to +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 From afd399d7d4c75c921252bbb6111436138e1ea27a Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Wed, 30 Jan 2019 11:43:30 +0000 Subject: [PATCH 4/4] remove unused schema defs --- .../event-schemas/m.presence_accept.yaml | 46 ---------------- .../event-schemas/m.presence_deny.yaml | 55 ------------------- .../event-schemas/m.presence_invite.yaml | 45 --------------- 3 files changed, 146 deletions(-) delete mode 100644 api/server-server/definitions/event-schemas/m.presence_accept.yaml delete mode 100644 api/server-server/definitions/event-schemas/m.presence_deny.yaml delete mode 100644 api/server-server/definitions/event-schemas/m.presence_invite.yaml diff --git a/api/server-server/definitions/event-schemas/m.presence_accept.yaml b/api/server-server/definitions/event-schemas/m.presence_accept.yaml deleted file mode 100644 index 3ba78b477..000000000 --- a/api/server-server/definitions/event-schemas/m.presence_accept.yaml +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -type: object -title: m.presence_accept -description: |- - An EDU representing approval for the observing user to subscribe to the - presence of the the observed user. -allOf: - - $ref: ../edu.yaml - - type: object - properties: - edu_type: - type: enum - enum: ['m.presence_accept'] - description: The string ``m.presence_accept`` - example: "m.presence_accept" - content: - type: object - description: The invite information. - title: Invite Information - properties: - observed_user: - type: string - description: |- - The user ID that has approved the ``observer_user`` to - subscribe to their presence. - example: "@alice:elsewhere.com" - observer_user: - type: string - description: |- - The user ID that requested to subscribe to the presence of - the ``observed_user``. - example: "@john:matrix.org" - required: ['observer_user', 'observed_user'] diff --git a/api/server-server/definitions/event-schemas/m.presence_deny.yaml b/api/server-server/definitions/event-schemas/m.presence_deny.yaml deleted file mode 100644 index 811c296a3..000000000 --- a/api/server-server/definitions/event-schemas/m.presence_deny.yaml +++ /dev/null @@ -1,55 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -type: object -title: m.presence_deny -description: |- - An EDU representing a declination or revocation for the observing user - to subscribe to the presence of the observed user. -example: { - "origin": "example.org", - "destination": "elsewhere.org", - "edu_type": "m.presence_deny", - "content": { - "observed_user": "@alice:elsewhere.org", - "observer_user": "@john:example.org" - } -} -allOf: - - $ref: ../edu.yaml - - type: object - properties: - edu_type: - type: enum - enum: ['m.presence_deny'] - description: The string ``m.presence_deny`` - example: "m.presence_deny" - content: - type: object - description: The invite information. - title: Invite Information - properties: - observed_user: - type: string - description: |- - The user ID that has declined or revoked the ``observer_user`` from - subscribing to their presence. - example: "@alice:elsewhere.com" - observer_user: - type: string - description: |- - The user ID that requested to subscribe to the presence of - the ``observed_user``. - example: "@john:matrix.org" - required: ['observer_user', 'observed_user'] diff --git a/api/server-server/definitions/event-schemas/m.presence_invite.yaml b/api/server-server/definitions/event-schemas/m.presence_invite.yaml deleted file mode 100644 index a584897b7..000000000 --- a/api/server-server/definitions/event-schemas/m.presence_invite.yaml +++ /dev/null @@ -1,45 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -type: object -title: m.presence_invite -description: |- - An EDU representing a request to subscribe to a user's presence. -allOf: - - $ref: ../edu.yaml - - type: object - properties: - edu_type: - type: enum - enum: ['m.presence_invite'] - description: The string ``m.presence_invite`` - example: "m.presence_invite" - content: - type: object - description: The invite information. - title: Invite Information - properties: - observed_user: - type: string - description: |- - The user ID the ``observer_user`` would like to subscribe - to the presence of. - example: "@alice:elsewhere.com" - observer_user: - type: string - description: |- - The user ID that is wishing to subscribe to the presence of - the ``observed_user``. - example: "@john:matrix.org" - required: ['observer_user', 'observed_user']