Document how presence EDUs work between servers

It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it.
pull/977/head
Travis Ralston 6 years ago
parent a77975ba68
commit 05a2427c73

@ -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']

@ -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']

@ -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']

@ -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']

@ -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")

@ -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
------------------------

Loading…
Cancel
Save