From 05a2427c7304292e48d9501574b7bdf006ce3153 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 19:51:05 -0600 Subject: [PATCH 01/10] 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. --- .../event-schemas/m.presence.accept.yaml | 45 +++++++++ .../event-schemas/m.presence.deny.yaml | 54 +++++++++++ .../event-schemas/m.presence.invite.yaml | 44 +++++++++ .../definitions/event-schemas/m.presence.yaml | 97 +++++++++++++++++++ scripts/templating/matrix_templates/units.py | 1 + specification/server_server_api.rst | 67 ++++--------- 6 files changed, 258 insertions(+), 50 deletions(-) create mode 100644 api/server-server/definitions/event-schemas/m.presence.accept.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.deny.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.invite.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.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 new file mode 100644 index 00000000..3b80ac44 --- /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 00000000..1383866c --- /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 00000000..eeb00ae3 --- /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 00000000..bebf8211 --- /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 88f7b86c..bb821097 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 a3d3f83a..d5177a04 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 ------------------------ From e7aed3da269387a28ed43b79c9d3eef66436845c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:16:39 -0600 Subject: [PATCH 02/10] Remove poll/unpoll from presence --- .../definitions/event-schemas/m.presence.yaml | 31 +------------------ specification/server_server_api.rst | 8 +---- 2 files changed, 2 insertions(+), 37 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index bebf8211..6d83b967 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -16,8 +16,6 @@ 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 @@ -35,7 +33,7 @@ allOf: type: array description: |- A list of presence updates that the receiving server is likely - to be interested in, or is subscribed to. + to be interested in. items: type: object title: User Presence Update @@ -67,31 +65,4 @@ allOf: 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/specification/server_server_api.rst b/specification/server_server_api.rst index d5177a04..6cc04d95 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -841,13 +841,7 @@ 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. - -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. +sending server's users to their presence list. .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence From ff1afaa8f7a4a5828d46a60d27ece5de985e8de3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:18:45 -0600 Subject: [PATCH 03/10] Add a note about how presence lists work --- specification/server_server_api.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 6cc04d95..236d90f5 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -843,6 +843,12 @@ 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. + .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence messages @@ -855,7 +861,7 @@ sending server's users to their presence list. {{definition_ss_event_schemas_m_presence_accept}} -{{definition_ss_event_schemas_m_presence_accept}} +{{definition_ss_event_schemas_m_presence_deny}} Querying for information ------------------------ From 549a25cad9b73df38d84b33e1837bf161f78b18b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:33:40 -0600 Subject: [PATCH 04/10] Add a mention about how currently_active works Reference: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/presence.py#L66-L68 --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 6d83b967..011db2ca 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -62,6 +62,8 @@ allOf: type: boolean description: |- Whether or not the user is currently using a device of theirs. + For example, if the user's ``last_active_ago`` was within the + last few minutes, they may be considered ``currently_active``. Defaults to false. example: true required: ['user_id', 'presence', 'last_active_ago'] From 766402a7025112569ddfe1efdc257513ff7d7ddf Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:34:08 -0600 Subject: [PATCH 05/10] Use strict types for the presence EDUs --- .../definitions/event-schemas/m.presence.accept.yaml | 3 ++- .../definitions/event-schemas/m.presence.deny.yaml | 3 ++- .../definitions/event-schemas/m.presence.invite.yaml | 3 ++- api/server-server/definitions/event-schemas/m.presence.yaml | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence.accept.yaml index 3b80ac44..72f932d2 100644 --- a/api/server-server/definitions/event-schemas/m.presence.accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.accept.yaml @@ -22,7 +22,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_accept'] description: The string ``m.presence_accept`` example: "m.presence_accept" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.deny.yaml b/api/server-server/definitions/event-schemas/m.presence.deny.yaml index 1383866c..3264a5af 100644 --- a/api/server-server/definitions/event-schemas/m.presence.deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.deny.yaml @@ -31,7 +31,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_deny'] description: The string ``m.presence_deny`` example: "m.presence_deny" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.invite.yaml b/api/server-server/definitions/event-schemas/m.presence.invite.yaml index eeb00ae3..8ae84872 100644 --- a/api/server-server/definitions/event-schemas/m.presence.invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.invite.yaml @@ -21,7 +21,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_invite'] description: The string ``m.presence_invite`` example: "m.presence_invite" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 011db2ca..f9e0499b 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -21,7 +21,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence'] description: The string ``m.presence`` example: "m.presence" content: From 96896fe5d6515a98f196556845f4e25fe48615d7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:34:50 -0600 Subject: [PATCH 06/10] Add a strict type the m.typing EDU --- api/server-server/definitions/event-schemas/m.typing.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index d4fa2f81..101d8d79 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -20,7 +20,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.typing'] description: The string ``m.typing`` example: "m.typing" content: From 750d4f9fdaaafac8b52c05828f2675d03c10df51 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 10:53:47 -0600 Subject: [PATCH 07/10] Rename the presence EDU files to be accurate to their types; Misc cleanup of titles --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- .../{m.presence.accept.yaml => m.presence_accept.yaml} | 2 +- .../{m.presence.deny.yaml => m.presence_deny.yaml} | 2 +- .../{m.presence.invite.yaml => m.presence_invite.yaml} | 2 +- api/server-server/definitions/event-schemas/m.receipt.yaml | 2 +- api/server-server/definitions/event-schemas/m.typing.yaml | 2 +- .../matrix_templates/templates/schema-definition.tmpl | 2 +- scripts/templating/matrix_templates/units.py | 1 - 8 files changed, 7 insertions(+), 8 deletions(-) rename api/server-server/definitions/event-schemas/{m.presence.accept.yaml => m.presence_accept.yaml} (97%) rename api/server-server/definitions/event-schemas/{m.presence.deny.yaml => m.presence_deny.yaml} (98%) rename api/server-server/definitions/event-schemas/{m.presence.invite.yaml => m.presence_invite.yaml} (97%) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index f9e0499b..8d4ef6e8 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence EDU +title: ``m.presence`` EDU description: |- An EDU representing presence updates for users of the sending homeserver. allOf: diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence_accept.yaml similarity index 97% rename from api/server-server/definitions/event-schemas/m.presence.accept.yaml rename to api/server-server/definitions/event-schemas/m.presence_accept.yaml index 72f932d2..4c39989b 100644 --- a/api/server-server/definitions/event-schemas/m.presence.accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_accept.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite Accept EDU +title: ``m.presence_accept`` EDU description: |- An EDU representing approval for the observing user to subscribe to the presence of the the 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 similarity index 98% rename from api/server-server/definitions/event-schemas/m.presence.deny.yaml rename to api/server-server/definitions/event-schemas/m.presence_deny.yaml index 3264a5af..1b9bff7d 100644 --- a/api/server-server/definitions/event-schemas/m.presence.deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_deny.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite Deny EDU +title: ``m.presence_deny`` EDU description: |- An EDU representing a declination or revocation for the observing user to subscribe to the presence of the 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 similarity index 97% rename from api/server-server/definitions/event-schemas/m.presence.invite.yaml rename to api/server-server/definitions/event-schemas/m.presence_invite.yaml index 8ae84872..4cdc58eb 100644 --- a/api/server-server/definitions/event-schemas/m.presence.invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite EDU +title: ``m.presence_invite`` EDU description: |- An EDU representing a request to subscribe to a user's presence. allOf: diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index 210988f9..58f47e3a 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Receipt EDU +title: ``m.receipt`` EDU description: |- An EDU representing receipt updates for users of the sending homeserver. When receiving receipts, the server should only update entries that are diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index 101d8d79..34b39529 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Typing Notification EDU +title: ``m.typing`` EDU description: A typing notification EDU for a user in a room. allOf: - $ref: ../edu.yaml diff --git a/scripts/templating/matrix_templates/templates/schema-definition.tmpl b/scripts/templating/matrix_templates/templates/schema-definition.tmpl index 42a7ae47..e2be12e8 100644 --- a/scripts/templating/matrix_templates/templates/schema-definition.tmpl +++ b/scripts/templating/matrix_templates/templates/schema-definition.tmpl @@ -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 %} diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index c1481430..90a87cd4 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -49,7 +49,6 @@ 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") From a4015d5c273ba308475d40bb5311d279fa6cdac9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 10:58:20 -0600 Subject: [PATCH 08/10] Spelling --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 8d4ef6e8..b9c5f754 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -56,7 +56,7 @@ allOf: type: integer format: int64 description: |- - The number of milliseconds that have ellapsed since the user + The number of milliseconds that have elapsed since the user last did something. example: 5000 currently_active: From e712466dca3370e6ca40755e3575da46a5cac87f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 10:44:28 -0600 Subject: [PATCH 09/10] Improve description for currently_active --- .../definitions/event-schemas/m.presence.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index b9c5f754..7a1dba60 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -62,10 +62,10 @@ allOf: currently_active: type: boolean description: |- - Whether or not the user is currently using a device of theirs. - For example, if the user's ``last_active_ago`` was within the - last few minutes, they may be considered ``currently_active``. - Defaults to false. + 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'] From 8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 11:03:26 -0600 Subject: [PATCH 10/10] Don't try and be fancy about titles --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- .../definitions/event-schemas/m.presence_accept.yaml | 2 +- .../definitions/event-schemas/m.presence_deny.yaml | 2 +- .../definitions/event-schemas/m.presence_invite.yaml | 2 +- api/server-server/definitions/event-schemas/m.receipt.yaml | 2 +- api/server-server/definitions/event-schemas/m.typing.yaml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 7a1dba60..7f47add4 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence`` EDU +title: m.presence description: |- An EDU representing presence updates for users of the sending homeserver. allOf: diff --git a/api/server-server/definitions/event-schemas/m.presence_accept.yaml b/api/server-server/definitions/event-schemas/m.presence_accept.yaml index 4c39989b..3ba78b47 100644 --- a/api/server-server/definitions/event-schemas/m.presence_accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_accept.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_accept`` EDU +title: m.presence_accept description: |- An EDU representing approval for the observing user to subscribe to the presence of the the 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 index 1b9bff7d..2eb6feec 100644 --- a/api/server-server/definitions/event-schemas/m.presence_deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_deny.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_deny`` EDU +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. diff --git a/api/server-server/definitions/event-schemas/m.presence_invite.yaml b/api/server-server/definitions/event-schemas/m.presence_invite.yaml index 4cdc58eb..a584897b 100644 --- a/api/server-server/definitions/event-schemas/m.presence_invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_invite`` EDU +title: m.presence_invite description: |- An EDU representing a request to subscribe to a user's presence. allOf: diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index 58f47e3a..7f13ebee 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.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 diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index 34b39529..ccbecf53 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.typing`` EDU +title: m.typing description: A typing notification EDU for a user in a room. allOf: - $ref: ../edu.yaml