diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence.accept.yaml new file mode 100644 index 000000000..3b80ac44d --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.accept.yaml @@ -0,0 +1,45 @@ +# 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: Presence Invite Accept EDU +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: string + 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 new file mode 100644 index 000000000..1383866c0 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.deny.yaml @@ -0,0 +1,54 @@ +# 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: Presence Invite Deny EDU +description: |- + An EDU representing a declination or revocation for the observing user + to subscribe to the presence of the observed user. +example: { + "origin": "domain.com", + "destination": "elsewhere.org", + "edu_type": "m.presence_deny", + "content": { + "observed_user": "@alice:elsewhere.org", + "observer_user": "@john:domain.com" + } +} +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + 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 new file mode 100644 index 000000000..eeb00ae32 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.invite.yaml @@ -0,0 +1,44 @@ +# 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: Presence Invite EDU +description: |- + An EDU representing a request to subscribe to a user's presence. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + 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'] diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml new file mode 100644 index 000000000..bebf8211b --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -0,0 +1,97 @@ +# 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: Presence EDU +description: |- + An EDU representing presence updates for users of the sending homeserver. + Can also be used to request additional presence updates for users of the + receiving homeserver. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.presence`` + example: "m.presence" + content: + type: object + description: The presence updates and requests. + title: Presence Update + properties: + push: + type: array + description: |- + A list of presence updates that the receiving server is likely + to be interested in, or is subscribed to. + items: + type: object + title: User Presence Update + properties: + user_id: + type: string + description: The user ID this presence EDU is for. + example: "@john:matrix.org" + presence: + type: enum + enum: ['offline', 'unavailable', 'online'] + description: The presence of the user. + example: "online" + status_msg: + type: string + description: An optional description to accompany the presence. + example: "Making cupcakes" + last_active_ago: + type: integer + format: int64 + description: |- + The number of milliseconds that have ellapsed since the user + last did something. + example: 5000 + currently_active: + type: boolean + description: |- + Whether or not the user is currently using a device of theirs. + Defaults to false. + example: true + required: ['user_id', 'presence', 'last_active_ago'] + poll: + type: array + description: |- + New user IDs that the sending server would like to subscribe to the + presence of. The sending server should not include users it has already + requested to be subscribed to. + + The receiving server should ensure the sending server has reasonable + interest in subscribing to the provided users. The receiver may ignore + a request to subscribe to a user the sender does not have reasonable + interest in. Reasonable interest may be residing in a room with the user, + being subscribed to a presence list, or some other requirement. + + If non-empty, the receiving server should immediately send the presence + updates to the sender for the users requested. + items: + type: string + example: ["@alice:elsewhere.org"] + unpoll: + type: array + description: |- + New user IDs the sending server is no longer interested in receiving + presence updates for. The sending server should not include users it + has previously requested to be unsubscribed from. + items: + type: string + example: ["@bob:elsewhere.org"] + required: ['push'] diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 88f7b86c2..bb8210976 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -49,6 +49,7 @@ SWAGGER_DEFINITIONS = { os.path.join(matrix_doc_dir, "api/identity/definitions"): "is", os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push", os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss", + os.path.join(matrix_doc_dir, "api/server-server/definitions/presence"): "ss_presence", } EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples") EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema") diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a3d3f83aa..d5177a047 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -838,57 +838,16 @@ Presence The server API for presence is based entirely on exchange of the following EDUs. There are no PDUs or Federation Queries involved. -Performing a presence update and poll subscription request:: +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. - EDU type: m.presence - - Content keys: - push: (optional): list of push operations. - Each should be an object with the following keys: - user_id: string containing a User ID - presence: "offline"|"unavailable"|"online"|"free_for_chat" - status_msg: (optional) string of free-form text - last_active_ago: milliseconds since the last activity by the user - - poll: (optional): list of strings giving User IDs - - unpoll: (optional): list of strings giving User IDs - -The presence of this combined message is two-fold: it informs the recipient -server of the current status of one or more users on the sending server (by the -``push`` key), and it maintains the list of users on the recipient server that -the sending server is interested in receiving updates for, by adding (by the -``poll`` key) or removing them (by the ``unpoll`` key). The ``poll`` and -``unpoll`` lists apply *changes* to the implied list of users; any existing IDs -that the server sent as ``poll`` operations in a previous message are not -removed until explicitly requested by a later ``unpoll``. - -On receipt of a message containing a non-empty ``poll`` list, the receiving -server should immediately send the sending server a presence update EDU of its -own, containing in a ``push`` list the current state of every user that was in -the original EDU's ``poll`` list. - -Sending a presence invite:: - - EDU type: m.presence_invite - - Content keys: - observed_user: string giving the User ID of the user whose presence is - requested (i.e. the recipient of the invite) - observer_user: string giving the User ID of the user who is requesting to - observe the presence (i.e. the sender of the invite) - -Accepting a presence invite:: - - EDU type: m.presence_accept - - Content keys - as for m.presence_invite - -Rejecting a presence invite:: - - EDU type: m.presence_deny - - Content keys - as for m.presence_invite +Servers may also request additional users by including them in the ``poll`` +array on an ``m.presence`` update. The receiving server may ignore users +requested in this array. The receiving server should maintain a list of +subscribed users for the sending server, which is appended to by the ``poll`` +array and deleted from by the ``unpoll`` array. .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence @@ -896,6 +855,14 @@ Rejecting a presence invite:: - Explain the zero-byte presence inference logic See also: docs/client-server/model/presence +{{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_accept}} + Querying for information ------------------------