Move lazy loading to a section in Filtering

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
+        If ``true``, enables lazy-loading of membership events. See
-        are those which are definitely necessary for a client to
+        `Lazy-loading room members <#lazy-loading-room-members>`_
-        display the ``sender`` of the timeline events in the response.
+        for more information. Defaults to ``false``.
-        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>`_.
     include_redundant_members:
       type: boolean
       description: |-
-        If ``true``, response will always contain the ``m.room.member``
+        If ``true``, enables redudant membership events. Does not
-        events required to display the ``sender`` of the timeline events
+        apply unless ``lazy_load_members`` is ``true``. See
-        in that response, assuming ``lazy_load_members`` is enabled.
+        `Lazy-loading room members <#lazy-loading-room-members>`_
-        This means that redundant duplicate member events will be returned
+        for more information. Defaults to ``false``.
-        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.
     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'``

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: []

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