Spec lazy-loading room members

api/client-server/definitions/room_event_filter.yaml

@@ -16,6 +16,19 @@ allOf:
 - type: object
   title: RoomEventFilter
   properties:
+    lazy_load_members:
+      type: boolean
+      description: |-
+        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``, enables redundant 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'``

api/client-server/definitions/sync_filter.yaml

@@ -47,7 +47,7 @@ properties:
       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'``
-          filter. This filter is applied before the filters in ``ephemeral``, 
+          filter. This filter is applied before the filters in ``ephemeral``,
           ``state``, ``timeline`` or ``account_data``
         items:
           type: string
@@ -73,33 +73,6 @@ properties:
         allOf:
         - $ref: room_event_filter.yaml
         description: The state events to include for rooms.
-        properties:
-          lazy_load_members:
-            type: boolean
-            description: |-
-              If ``true``, the only ``m.room.member`` events returned in
-              the ``state`` section of the ``/sync`` response are those
-              which are definitely necessary for a client to display
-              the ``sender`` of the timeline events in that 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 to ``/sync``, given that most clients
-              cache membership events (see ``include_redundant_members``
-              to change this behaviour).
-          include_redundant_members:
-            type: boolean
-            description: |-
-              If ``true``, the ``state`` section of the ``/sync`` 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
-              ``/sync``. 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 to ``/sync``.
-              If ``lazy_load_members`` is ``false`` this field is ignored.
-
       timeline:
         allOf:
         - $ref: room_event_filter.yaml

api/client-server/event_context.yaml

@@ -34,6 +34,9 @@ paths:
         This API returns a number of events that happened just before and
         after the specified event. This allows clients to get the context
         surrounding an event.
+
+        *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_
+        for more information.
       operationId: getEventContext
       security:
         - accessToken: []

api/client-server/message_pagination.yaml

@@ -33,6 +33,9 @@ paths:
       description: |-
         This API returns a list of message and state events for a room. It uses
         pagination query parameters to paginate history in the room.
+
+        *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_
+        for more information.
       operationId: getRoomEvents
       security:
         - accessToken: []
@@ -108,6 +111,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 lazy-loading aware endpoints 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",

api/client-server/rooms.yaml

@@ -288,6 +288,44 @@ paths:
           description: The room to get the member events for.
           required: true
           x-example: "!636q39766251:example.com"
+        - in: query
+          name: at
+          type: string
+          description: |-
+            The point in time (pagination token) to return members for in the room.
+            This token can be obtained from a ``prev_batch`` token returned for
+            each room by the sync API. Defaults to the current state of the room,
+            as determined by the server.
+          x-example: "YWxsCgpOb25lLDM1ODcwOA"
+        # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
+        # filter might be a better alternative.
+        # See https://github.com/matrix-org/matrix-doc/issues/1337
+        - in: query
+          name: membership
+          type: string
+          enum:
+            - join
+            - invite
+            - leave
+            - ban
+          description: |-
+            The kind of membership to filter for. Defaults to no filtering if
+            unspecified. When specified alongside ``not_membership``, the two
+            parameters create an 'or' condition: either the membership *is*
+            the same as ``membership`` **or** *is not* the same as ``not_membership``.
+          x-example: "join"
+        - in: query
+          name: not_membership
+          type: string
+          enum:
+            - join
+            - invite
+            - leave
+            - ban
+          description: |-
+            The kind of membership to exclude from the results. Defaults to no
+            filtering if unspecified.
+          x-example: leave
       security:
         - accessToken: []
       responses:

api/client-server/sync.yaml

@@ -34,6 +34,17 @@ paths:
         Clients use this API when they first log in to get an initial snapshot
         of the state on the server, and then continue to call this API to get
         incremental deltas to the state, and to receive new messages.
+
+        *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_
+        for more information. Lazy-loading members is only supported on a ``StateFilter``
+        for this endpoint. When lazy-loading is enabled, servers MUST include the
+        syncing user's own membership event when they join a room, or when the
+        full state of rooms is requested. The user's own membership event is eligible
+        for being considered redundant by the server. When a sync is ``limited``,
+        the server MUST return membership events for events in the gap (from ``since``),
+        even if the applicable events are not in the response, regardless as to whether
+        or not they are redundant. ``include_redundant_members`` is ignored for limited
+        syncs.
       operationId: sync
       security:
         - accessToken: []
@@ -49,6 +60,8 @@ paths:
             requests. Creating a filter using the filter API is recommended for
             clients that reuse the same filter multiple times, for example in
             long poll requests.
+
+            See `Filtering <#filtering>`_ for more information.
           x-example: "66696p746572"
         - in: query
           name: since
@@ -125,6 +138,50 @@ paths:
                       title: Joined Room
                       type: object
                       properties:
+                        summary:
+                          title: RoomSummary
+                          type: object
+                          description: |-
+                            Information about the room which clients may need to
+                            correctly render it to users.
+                          properties:
+                            "m.heroes":
+                              type: array
+                              description: |-
+                                The users which can be used to generate a room name
+                                if the room does not have one. Required if the room
+                                does not have a ``m.room.name`` or ``m.room.canonical_alias``
+                                state event with non-empty content.
+
+                                This should be the first 5 members of the room, ordered
+                                by stream ordering, which are joined or invited. The
+                                list must never include the client's own user ID. When
+                                no joined or invited members are available, this should
+                                consist of the banned and left users. More than 5 members
+                                may be provided, however less than 5 should only be provided
+                                when there are less than 5 members to represent.
+
+                                When lazy-loading room members is enabled, the membership
+                                events for the heroes MUST be included in the ``state``,
+                                unless they are redundant. When the list of users changes,
+                                the server notifies the client by sending a fresh list of
+                                heroes. If there are no changes since the last sync, this
+                                field may be omitted.
+                              items:
+                                type: string
+                            "m.joined_member_count":
+                              type: integer
+                              description: |-
+                                 The number of users with ``membership`` of ``join``,
+                                 including the client's own user ID. If this field has
+                                 not changed since the last sync, it may be omitted.
+                                 Required otherwise.
+                            "m.invited_member_count":
+                              type: integer
+                              description: |-
+                                 The number of users with ``membership`` of ``invite``.
+                                 If this field has not changed since the last sync, it
+                                 may be omitted. Required otherwise.
                         state:
                           title: State
                           type: object
@@ -330,6 +387,14 @@ paths:
                 "rooms": {
                   "join": {
                     "!726s6s6q:example.com": {
+                      "summary": {
+                        "m.heroes": [
+                          "@alice:example.com",
+                          "@bob:example.com"
+                        ],
+                        "m.joined_member_count": 2,
+                        "m.invited_member_count": 0
+                      },
                       "state": {
                         "events": [
                           {

changelogs/client_server/newsfragments/2035.feature

@@ -0,0 +1 @@
+Add the option to lazy-load room members for increased client performance.

specification/client_server_api.rst

@@ -1268,6 +1268,47 @@ 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 ``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.
+
+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.
+
+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