From 34d6c1f4ad60d7d753ac703613034a8756662ae8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 14:46:59 -0600 Subject: [PATCH] Clarify wording further for how to handle redundant members Note: This makes assumptions on what the TODO comment in Synapse means: https://github.com/matrix-org/synapse/blob/e26e6b3230f0b55376f0f3bf823dd789ac7064d0/synapse/handlers/pagination.py#L262 Due to lack of implementation, it is assumed that using the same filter across multiple calls to /sync OR /messages will result in the redundant members being excluded in the next request. For example, calling /sync, then /messages which returns some members, then /sync again will exclude the members due to them being in /messages. --- .../definitions/room_event_filter.yaml | 25 ++++++++++--------- api/client-server/message_pagination.yaml | 17 +++++++++++++ 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 5258ea30..35b3edf9 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -24,27 +24,28 @@ allOf: display the ``sender`` of the timeline events in the response. If ``false``, ``m.room.member`` events are not filtered. By default, servers should suppress duplicate redundant - lazy-loaded ``m.room.member`` events from being sent to a given - client across multiple calls, given that most clients - cache membership events (see ``include_redundant_members`` - to change this behaviour). + lazy-loaded ``m.room.member`` events from being sent to a + given client in a previous request using the same filter, + given that most clients cache membership events (see + ``include_redundant_members`` to change this behaviour). Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages``. + ``state`` section of a ``/sync`` or ``/messages`` response. include_redundant_members: type: boolean description: |- If ``true``, response will always contain the ``m.room.member`` events required to display the ``sender`` of the timeline events - in that response, assuming ``lazy_load_members`` is enabled. This - means that redundant duplicate member events may be returned across - multiple calls to. This is useful for naive clients who never track - membership data. If ``false``, duplicate ``m.room.member`` events - may be suppressed by the server across multiple calls. If - ``lazy_load_members`` is ``false`` this field is ignored. + in that response, assuming ``lazy_load_members`` is enabled. + This means that redundant duplicate member events will be returned + across multiple calls using the same filter. This is useful for + naive clients who never track membership data. If ``false`` or + not provided, duplicate ``m.room.member`` events should be + suppressed by the server across multiple calls. If ``lazy_load_members`` + is ``false`` this field is ignored. Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages``. + ``state`` section of a ``/sync`` or ``/messages`` response. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 941e61fb..ff6d970d 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -108,6 +108,23 @@ paths: type: object title: RoomEvent "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml" + state: + type: array + description: |- + A list of state events relevant to showing the ``chunk``. For example, if + lazy-loading members is enabled in the filter then this will contain any + applicable membership events. Servers should be careful to not exclude + membership events which are older than ones already sent to the client. + Likewise, clients should be cautious and avoid using older membership + events as the current membership event when paginating backwards. + + Unless ``include_redundant_members`` is ``true``, the server should remove + redundant members which would have already been sent to clients in prior calls + to ``/messages`` or ``/sync`` with the same filter. + items: + type: object + title: RoomStateEvent + $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml" examples: application/json: { "start": "t47429-4392820_219380_26003_2265",