-
Notifications
You must be signed in to change notification settings - Fork 384
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
MSC3706: Extensions to `/_matrix/federation/v2/send_join/{roomId}/{ev…
…entId}` for partial state (#3706)
- Loading branch information
Showing
1 changed file
with
122 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,122 @@ | ||
# 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. |