wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #2035 from matrix-org/travis/1.0/msc688-msc1227-lazy-loading

Browse source 
Spec lazy-loading room members
This commit is contained in:
Travis Ralston 2019-06-11 09:39:32 -06:00 • committed by GitHub
commit 19f017f9bd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 233 additions and 86 deletions
Download patch file Download diff file Expand all files Collapse all files

60
specification/client_server_api.rst
View file

@ -1317,6 +1317,66 @@ 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 attempt to only send membership events
which are relevant to the client.
It is important to understand that lazy-loading is not intended to be a
perfect optimisation, and that it may not be practical for the server to
calculate precisely which membership events are relevant to the client. As a
result, it is valid for the server to send redundant membership events to the
client to ease implementation, although such redundancy should be minimised
where possible to conserve bandwidth.
In terms of filters, lazy-loading is enabled by enabling ``lazy_load_members``
on a ``RoomEventFilter`` (or a ``StateFilter`` in the case of ``/sync`` only).
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.
When processing a sequence of events (e.g. by looping on ``/sync`` or
paginating ``/messages``), it is common for blocks of events in the sequence
to share a similar set of senders. Rather than responses in the sequence
sending duplicate membership events for these senders to the client, the
server MAY assume that clients will remember membership events they have
already been sent, and choose to skip sending membership events for members
whose membership has not changed. These are called 'redundant membership
events'. Clients may request that redundant membership events are always
included in responses by setting ``include_redundant_members`` to true in the
filter.
The expected pattern for using lazy-loading is currently:
* Client performs an initial /sync with lazy-loading enabled, and receives
only the membership events which relate to the senders of the events it
receives.
* Clients which support display-name tab-completion or other operations which
require rapid access to all members in a room should call /members for the
currently selected room, with an ``?at`` parameter set to the /sync
response's from token. The member list for the room is then maintained by
the state in subsequent incremental /sync responses.
* Clients which do not support tab-completion may instead pull in profiles for
arbitrary users (e.g. read receipts, typing notifications) on demand by
querying the room state or ``/profile``.
.. TODO-spec
This implies that GET /state should also take an ``?at`` param
The current endpoints which support lazy-loading room members are:
* |/sync|_
* |/rooms/<room_id>/messages|_
* |/rooms/{roomId}/context/{eventId}|_
API endpoints
~~~~~~~~~~~~~
{{filter_cs_http_api}}
Events