You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/proposals/3706-partial-state-in-send-...

123 lines
5.2 KiB
Markdown

# MSC3706: Extensions to `/_matrix/federation/v2/send_join/{roomId}/{eventId}` for partial state
## Background
It is well known that joining large rooms over federation can be very slow (see,
for example, [synapse#1211](https://github.com/matrix-org/synapse/issues/1211)).
Much of the reason for this is the large number of events which are returned by
the [`/send_join`](https://spec.matrix.org/v1.2/server-server-api/#put_matrixfederationv2send_joinroomideventid)
API, and must be validated and stored.
[MSC3902](https://github.com/matrix-org/matrix-doc/pull/3902) gives an overview
of changes to the matrix protocol to improve this situation. This MSC focuses
on a specific aspect of those suggestions by proposing specific changes to the
`/send_join` API.
## Proposal
[`PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}`](https://spec.matrix.org/v1.2/server-server-api/#put_matrixfederationv2send_joinroomideventid)
is extended to support "partial state" in its responses. This involves the
following changes.
### New query parameter
`omit_members` is added as a new query parameter. This can take the values
`true` or `false`; other values should be rejected with an HTTP 400 error with
matrix error code `M_INVALID_PARAM`.
Calling servers use this parameter to indicate support for partial state in
`send_join`. If it is not set to `true`, receiving servers continue to behave
as they do today.
### Changes to the response
Receiving servers are not obliged to implement partial state: they are also
free to support it for some rooms and not others.
The following changes are made to the response:
* `members_omitted`: a new boolean field is added. This should be set to `true`
to indicate that `m.room.member` events have been omitted from the response.
It must otherwise be set to `false` or omitted.
* `state`: if partial state is being returned, then state events with event
type `m.room.member` are omitted from the response. All other room state is
returned as normal. (See 'Alternatives' for discussion on why only
`m.room.member` events are omitted.)
* `auth_chain`: The spec currently defines this as "The auth chain for the
entire current room state". We instead rephrase this as:
> All events in the auth chain for the returned join event, as well as
> those in the auth chains for any events returned in `state`.
(Note that in the case that full state is being returned, the two
definitions are equivalent.)
* If the `omit_members` query parameter was set, we make a further
optimisation to `auth_chain`:
> Any events returned within `state` can be omitted from `auth_chain`.
For example: the `m.room.create` event is part of the room state, so
must be included in `state`. However, it also forms part of the auth chain
for all of the returned events, so in the current spec, must *also* be
included in `auth_chain`. However, this is redundant, so we should omit it
for calling servers which opt into that via the `omit_members` query param.
* `servers_in_room`: A new field of type `[string]`, listing the servers
active in the room (ie, those with joined members) before the join.
This is to be used by the joining server to send outgoing federation
transactions while it synchronises the full state, as outlined in [MSC3902](https://github.com/matrix-org/matrix-spec-proposals/pull/3902).
This field is **required** if the `members_omitted` response field is true; it
is otherwise optional.
## Potential issues
None at present.
## Alternatives
* In future, the list of event types to omit could be expanded. (Some rooms
may have large numbers of other state events).
Currently, `m.room.member` events are by far the biggest problem. For
example, a `/send_join` request for Matrix HQ returns approximately 85000
events in `state`, of which all but 44 are `m.room.member`.
Additionally: the client-server API already provides a mechanism for
omitting `m.room.member` events from the `/sync` response, via
[lazy loading](https://spec.matrix.org/v1.4/client-server-api/#lazy-loading-room-members),
which means that this change can be implemented without changes to the
client-server API. Extending the list of event types to be omitted would
require changes to the client-server API and therefore be significantly more
involved.
In order to reduce the scope of the change, we have therefore decided to
focus on `m.room.member` events for now. Future MSCs might provide a
mechanism for omitting other event types.
## Security considerations
No security issues are currently foreseen with this specific MSC, though the
larger topic of incremental synchronisation of state has several concerns;
these will be discussed in other MSCs such as MSC3902.
## Unstable prefix
The following mapping will be used for identifiers in this MSC during
development:
Proposed final identifier | Purpose | Development identifier
------------------------- | --------------- | ----
`omit_members` | query parameter | `org.matrix.msc3706.partial_state`
`members_omitted` | response field | `org.matrix.msc3706.partial_state`
`servers_in_room` | response field | `org.matrix.msc3706.servers_in_room`
## Dependencies
This MSC does not build on any existing unaccepted MSCs.