From ba520df004eafdf3fc58d051a567708d7419fe14 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 17:38:04 -0600 Subject: [PATCH] Move lazy loading to a section in Filtering --- .../definitions/room_event_filter.yaml | 36 ++++--------------- api/client-server/sync.yaml | 3 +- specification/client_server_api.rst | 33 +++++++++++++++++ 3 files changed, 42 insertions(+), 30 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 4790643e..0659be8e 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -19,38 +19,16 @@ allOf: lazy_load_members: type: boolean description: |- - If ``true``, the only ``m.room.member`` events returned - are those which are definitely necessary for a client to - 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 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 lazy-loading aware endpoint. - - The endpoints which support lazy-loading are: - `/sync <#get-matrix-client-%CLIENT_RELEASE_LABEL%-sync>`_, - `/messages <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-messages>`_, - and `/context <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-context-eventid>`_. + If ``true``, enables lazy-loading of membership events. See + `Lazy-loading room members <#lazy-loading-room-members>`_ + for more information. Defaults to ``false``. 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 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 lazy-loading aware endpoint. + If ``true``, enables redudant membership events. Does not + apply unless ``lazy_load_members`` is ``true``. See + `Lazy-loading room members <#lazy-loading-room-members>`_ + for more information. Defaults to ``false``. 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/sync.yaml b/api/client-server/sync.yaml index 87e7bf74..bd659369 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -36,7 +36,8 @@ paths: incremental deltas to the state, and to receive new messages. *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ - for more information. + for more information. Lazy-loading members is only supported on a ``StateFilter`` + for this endpoint. operationId: sync security: - accessToken: [] diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 604c2b1c..a4b8dd5c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1268,6 +1268,39 @@ Filters can be created on the server and can be passed as as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters. +Lazy-loading room members +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Membership events often take significant resources for clients to track. In an +effort to reduce the number of resources used, clients can enable "lazy-loading" +for room members. By doing this, servers will only ever send membership events +which are relevant to the client. + +In terms of filters, this means enabling ``lazy_load_members`` on a ``StateFilter`` +or ``RoomEventFilter``. When enabled, lazy-loading aware endpoints (see below) +will only include membership events for the ``sender`` of events being included +in the response. For example, if a client makes a ``/sync`` request with lazy-loading +enabled, the server will only return membership events for the ``sender`` of events +in the timeline, not all members of a room. + +Repeated calls to lazy-loading aware endpoints will result in redundant membership +events being excluded by default. Clients often track which membership events they +already have, therefore making the extra information not as useful to the client. +Clients can always request redundant members by setting ``include_redundant_members`` +to true in the filter. + +Servers should be cautious about which events they consider redundant. Membership +events can change over time, and should be included as relevant to maintain the +historical record. Likewise, clients should be cautious about treating an older event +as the current membership event for a user. + +.. Note:: + Repeated calls using the same filter to *any* lazy-loading aware endpoint may + result in redundant members being excluded from future calls. For example, a + request to ``/sync`` followed by a request to ``/messages`` may result in a + future call to ``/sync`` excluding members included by the ``/messages`` call. + + {{filter_cs_http_api}} Events