Document how read receipts work over federation

Federation format: d69decd5c7/synapse/handlers/receipts.py (L153-L166)

Population of the fields that the above uses to construct the EDU: d69decd5c7/synapse/handlers/receipts.py (L48-L56)
pull/1484/head
Travis Ralston 6 years ago
parent a77975ba68
commit e03bfbc47b

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

@ -896,6 +896,18 @@ Rejecting a presence invite::
- Explain the zero-byte presence inference logic - Explain the zero-byte presence inference logic
See also: docs/client-server/model/presence 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 Querying for information
------------------------ ------------------------

Loading…
Cancel
Save