wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1482 from turt2live/travis/s2s/presence

Browse source 
Document how presence EDUs work between servers
This commit is contained in:
Travis Ralston 2018-08-21 11:26:32 -06:00 • committed by GitHub
commit 1d7ea314d4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 240 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

71
api/server-server/definitions/event-schemas/m.presence.yaml Normal file
View file

@ -0,0 +1,71 @@
# 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
description: |-
An EDU representing presence updates for users of the sending homeserver.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence']
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.
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 elapsed since the user
last did something.
example: 5000
currently_active:
type: boolean
description: |-
True if the user is likely to be interacting with their
client. This may be indicated by the user having a
``last_active_ago`` within the last few minutes. Defaults
to false.
example: true
required: ['user_id', 'presence', 'last_active_ago']
required: ['push']

46
api/server-server/definitions/event-schemas/m.presence_accept.yaml Normal file
View file

@ -0,0 +1,46 @@
# 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']

55
api/server-server/definitions/event-schemas/m.presence_deny.yaml Normal file
View file

@ -0,0 +1,55 @@
# 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": "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: 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']

45
api/server-server/definitions/event-schemas/m.presence_invite.yaml Normal file
View file

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

2
api/server-server/definitions/event-schemas/m.receipt.yaml
View file

@ -13,7 +13,7 @@
# limitations under the License.
type: object
title: Receipt EDU
title: m.receipt
description: |-
An EDU representing receipt updates for users of the sending homeserver.
When receiving receipts, the server should only update entries that are

5
api/server-server/definitions/event-schemas/m.typing.yaml
View file

@ -13,14 +13,15 @@
# limitations under the License.
type: object
title: Typing Notification EDU
title: m.typing
description: A typing notification EDU for a user in a room.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: string
type: enum
enum: ['m.typing']
description: The string ``m.typing``
example: "m.typing"
content:

2
scripts/templating/matrix_templates/templates/schema-definition.tmpl
View file

@ -1,6 +1,6 @@
{% import 'tables.tmpl' as tables -%}
``{{definition.title}}`` Schema
``{{definition.title}}`` schema
{{(11 + definition.title | length) * title_kind}}
{% if 'description' in definition %}

68
specification/server_server_api.rst
View file

@ -827,57 +827,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
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.
.. TODO-doc
- Explain the timing-based round-trip reduction mechanism for presence
@ -885,6 +844,15 @@ 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_deny}}
Receipts
--------