From e03bfbc47b5079a7bd54bbce1a4996524b6fc617 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 22:52:33 -0600 Subject: [PATCH 1/5] Document how read receipts work over federation Federation format: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L153-L166 Population of the fields that the above uses to construct the EDU: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L48-L56 --- .../definitions/event-schemas/m.receipt.yaml | 82 +++++++++++++++++++ specification/server_server_api.rst | 12 +++ 2 files changed, 94 insertions(+) create mode 100644 api/server-server/definitions/event-schemas/m.receipt.yaml diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml new file mode 100644 index 00000000..b8638427 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -0,0 +1,82 @@ +# 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: 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 + listed in the EDU. Receipts previously received that do not appear in the + EDU should not be removed or otherwise manipulated. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.receipt`` + example: "m.receipt" + content: + type: object + description: |- + Receipts for a particular room. The string key is the room ID for + which the receipts under it belong. + additionalProperties: + type: object + title: Room Receipts + properties: + # We strongly define the receipt type to help spec future ones later + # on. At that point, m.read can become optional (maybe). + "m.read": + type: object + description: Read receipts for users in the room. + title: User Read Receipt + properties: + event_ids: + type: array + description: |- + The event ID that the user has read up to. Must be exactly + one element in length. + minItems: 1 + maxItems: 1 + items: + type: string + example: ['$read_this_event:matrix.org'] + data: + type: object + description: Metadata for the read receipt. + title: Read Receipt Metadata + properties: + ts: + type: integer + format: int64 + description: |- + A POSIX timestamp in milliseconds for when the user read + the event specified in the read receipt. + example: 1533358089009 + required: ['ts'] + required: ['event_ids', 'data'] + required: ['m.read'] + example: { + "!some_room:domain.com": { + "m.read": { + "@john:matrix.org": { + "event_ids": ["$read_this_event:matrix.org"], + "data": { + "ts": 1533358089009 + } + } + } + } + } diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a3d3f83a..f19f41a6 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -896,6 +896,18 @@ Rejecting a presence invite:: - Explain the zero-byte presence inference logic See also: docs/client-server/model/presence +Receipts +-------- + +Receipts are EDUs used to communicate a marker for a given event. Currently the +only kind of receipt supported is a "read receipt", or where in the timeline a +user has read up to. + +Read receipts for events events that a user sent do not need to be sent. It is +implied that by sending the event the user has read up to the event. + +{{definition_ss_event_schemas_m_receipt}} + Querying for information ------------------------ From c891e4a957d4e004517c3fbe5978da4764b7555b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 16 Aug 2018 12:39:47 -0600 Subject: [PATCH 2/5] Require the push gateway URL to be of a specific path --- api/client-server/pusher.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 34050d3f..3bedf866 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -222,7 +222,9 @@ paths: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send - notifications to. + notifications to. MUST be an HTTPS URL with a path pointing + to ``/_matrix/push/v1/notify``. + example: "https://push-gateway.location.here/_matrix/push/v1/notify" format: type: string description: |- From 5b30d33b89541d5398901fe73eeac73dc1a29cc2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 02:51:41 -0600 Subject: [PATCH 3/5] Simpler language --- api/client-server/pusher.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 3bedf866..d232baf9 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -222,8 +222,8 @@ paths: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send - notifications to. MUST be an HTTPS URL with a path pointing - to ``/_matrix/push/v1/notify``. + notifications to. MUST be an HTTPS URL with a path of + ``/_matrix/push/v1/notify``. example: "https://push-gateway.location.here/_matrix/push/v1/notify" format: type: string From 44d1f8dbe5bf5826357d1d86d01c4897d3c83acd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:46:11 -0600 Subject: [PATCH 4/5] s/timeline/event graph --- specification/server_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f19f41a6..150e69e0 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -900,8 +900,8 @@ Receipts -------- Receipts are EDUs used to communicate a marker for a given event. Currently the -only kind of receipt supported is a "read receipt", or where in the timeline a -user has read up to. +only kind of receipt supported is a "read receipt", or where in the event graph +the user has read up to. Read receipts for events events that a user sent do not need to be sent. It is implied that by sending the event the user has read up to the event. From c492fe43b5d42f7f9d14228973e12b8a744ce3b8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:46:31 -0600 Subject: [PATCH 5/5] Add strict typing to the m.receipt EDU; Fix description of event_ids --- api/server-server/definitions/event-schemas/m.receipt.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index b8638427..210988f9 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -24,7 +24,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.receipt'] description: The string ``m.receipt`` example: "m.receipt" content: @@ -46,8 +47,7 @@ allOf: event_ids: type: array description: |- - The event ID that the user has read up to. Must be exactly - one element in length. + The extremity event IDs that the user has read up to. minItems: 1 maxItems: 1 items: